diff --git a/.squad/agents/beast/history.md b/.squad/agents/beast/history.md index 07cf97f3d..02917a55d 100644 --- a/.squad/agents/beast/history.md +++ b/.squad/agents/beast/history.md @@ -6,6 +6,8 @@ - **Created:** 2026-02-10 +📌 Team update (2026-03-24): Documentation task breakdown complete — 8 GitHub issues (#505–#512) created for component doc syntax conversions, ViewState/PostBack migration guide, and cross-linking. Issues labeled squad+type:docs. Coordinate with Forge for content review. #508 (ViewState docs) blocks on PR #503 merge. — decided by Forge + 📌 Team update (2026-03-17): HttpHandlerBase implementation complete (7 files in Handlers/). Returns IEndpointConventionBuilder; Session markers added; build passes 0 errors. — decided by Cyclops ## Core Context diff --git a/.squad/agents/cyclops/history.md b/.squad/agents/cyclops/history.md index 225c4f8b3..b1e7419cb 100644 --- a/.squad/agents/cyclops/history.md +++ b/.squad/agents/cyclops/history.md @@ -60,6 +60,8 @@ --- ## Active Decisions & Alerts +📌 **Team update (2026-03-24):** ViewState Phase 1 implementation complete & merged — `feature/viewstate-postback-shim` ready. ViewStateDictionary core, mode-adaptive IsPostBack, SSR hidden field round-trip, IDataProtectionProvider integration, CryptographicException fallback. All 2588 tests pass (2 breaking contracts fixed by Coordinator). Phase 2 (SSR persistence integration) approved. — decided by Cyclops + 📌 **Team update (2026-03-17):** HttpHandlerBase implementation validated by Rogue — 94 tests passing, all adapter patterns verified correct. Commit 040fbad5 (15 files, 3218 insertions) on feature/httphandler-base ready for integration. — decided by Rogue 📌 **Team update (2026-03-17):** Fixed #471 (GUID IDs) and #472 (L1 script). CheckBox/RadioButton/RadioButtonList now use ClientID exclusively; no GUID fallbacks. L1 script test suite: 7/10 → 15/15 (100%). All 2105 tests pass. — decided by Cyclops @@ -578,3 +580,17 @@ Team update: ModalPopupExtender and CollapsiblePanelExtender implemented by Cycl **Key patterns applied:** var everywhere (IDE0007), WebUtility.HtmlEncode instead of HttpUtility, Blazor route URLs instead of .aspx, `new()` target-typed syntax. **Build:** 0 errors, 0 warnings (excluding pre-existing NU1510 from upstream deps). +### ViewState + IsPostBack Phase 1 Core Infrastructure (2026-03-24) + +**Summary:** Implemented Phase 1 of the ViewState/PostBack shim per Forge's architecture proposal. Created ViewStateDictionary class implementing IDictionary with null-safe indexer (Web Forms compat), type-safe convenience methods, IsDirty tracking, and IDataProtector-based Serialize/Deserialize with JsonElement type coercion. Updated BaseWebFormsComponent: ViewState upgraded from Dictionary to ViewStateDictionary, [Obsolete] removed, IsPostBack with mode-adaptive logic (SSR checks HTTP method, Interactive tracks _hasInitialized), CurrentRenderMode/IsHttpContextAvailable, RenderViewStateField, IDataProtectionProvider injection, ViewState deserialization from form POST. Updated WebFormsPageBase similarly. Created WebFormsRenderMode enum. + +**Key decisions:** +- IDataProtectionProvider is injected as nullable (null-safe) backward compat for apps that don't register DataProtection +- ViewState deserialization happens BEFORE OnInit/OnLoad events in OnInitializedAsync matches Web Forms lifecycle +- CryptographicException from tampered payloads silently fails to empty ViewState (fail-safe) +- Component ID for hidden field uses the developer-set `ID` parameter (`__bwfc_viewstate_{ID}`) +- `var` used everywhere per IDE0007 enforcement + +**Files created:** ViewStateDictionary.cs, WebFormsRenderMode.cs +**Files modified:** BaseWebFormsComponent.cs, WebFormsPageBase.cs +**Build:** 0 errors, 122 warnings (all pre-existing) diff --git a/.squad/agents/forge/history.md b/.squad/agents/forge/history.md index 07a531410..9fd0b9c08 100644 --- a/.squad/agents/forge/history.md +++ b/.squad/agents/forge/history.md @@ -5,9 +5,9 @@ - **Stack:** C#, Blazor, .NET, ASP.NET Web Forms, bUnit, xUnit, MkDocs, Playwright - **Created:** 2026-02-10 -## Core Context +## Active Decisions & Alerts - +📌 **Team update (2026-03-24):** ViewState Phase 1 architecture implemented — ViewStateDictionary (SSR + Interactive modes), mode-adaptive IsPostBack, hidden form field encryption, IDataProtectionProvider optional integration, CryptographicException fail-safe. Phase 2 (SSR persistence, AutoPostBack, analyzers, docs) planned for 7 weeks. Cyclops implementation validated; all 2588 tests pass. — decided by Forge M1–M16: 6 PRs reviewed, Calendar/FileUpload rejected, ImageMap/PageService approved, ASCX/Snippets shelved. M2–M3 shipped (50/53 controls, 797 tests). Chart.js for Chart. DataBoundStyledComponent recommended. Key patterns: Enums/ with int values, On-prefix events, feature branches→upstream/dev, ComponentCatalog.cs. Deployment: Docker+NBGV, dual NuGet, Azure webhook. M7–M14 milestone plans. HTML audit: 3 tiers, M11–M13. M15 fidelity: 132→131 divergences, 5 fixable bugs. Data controls: 90%+ sample parity, 4 remaining bugs. M17 AJAX: 6 controls shipped. @@ -671,3 +671,35 @@ Analysis written to `.squad/decisions/inbox/forge-departmentportal-migration-pla Plan written to session workspace plan.md. Architecture decisions written to `.squad/decisions/inbox/forge-p1p5-plan.md`. 📡 Team update (2026-03-22): P1–P5 implementation plan completed — 6 phases, 4 new files, 4 modified files, ~9 days. Execution order: P2→P3→P1→P4→P5→FindControl. Key: WebControl gets proper Render pipeline, 4 new shim types, namespace stays in BWFC.CustomControls. ✅ decided by Forge + +### Documentation Improvement Task Decomposition (2025-01-24) + +**Task:** Break down remaining documentation work (from PR #504 audit and ViewState Phase 1 PR #503) into actionable GitHub issues. + +**Deliverable:** 8 GitHub issues created on FritzAndFriends/BlazorWebFormsComponents: +- #505: Convert DataControls documentation to tabbed syntax (GridView, Repeater, DataGrid, DataList, ListView, DetailsView, FormView, Chart, DataPager, PagerSettings) +- #506: Convert ValidationControls documentation to tabbed syntax (BaseValidator, BaseCompareValidator, RequiredFieldValidator, CompareValidator, RangeValidator, RegularExpressionValidator, CustomValidator, ValidationSummary) +- #507: Expand stub documentation (RegularExpressionValidator _TODO_, ValidationSummary stub with headers only, Label incomplete) +- #508: Document ViewState and PostBack shim features from PR #503 (create ViewStateAndPostBack.md migration guide, document ViewStateDictionary, IsPostBack, hidden field persistence) +- #509: Complete User-Controls.md migration guide (expand with ViewState patterns, state management, PostBack handling, working examples) +- #510: Add cross-linking between related components (validation ↔ each other, list controls ↔ variants, data controls ↔ each other) +- #511: Update mkdocs.yml navigation (add new migration guides, verify all docs indexed) +- (#504 EditorControls conversion was also created but not queried in final list) + +**Key scoping decisions:** + +1. **Batch by component family** — Groups related controls together for efficient parallel work. EditorControls (22+ files), DataControls (10 files), ValidationControls (10 files) are three independent conversion tracks. + +2. **Stubs expanded during conversion** — Don't create separate tasks for expanding RegularExpressionValidator/ValidationSummary. These are handled as part of ValidationControls conversion (#506). + +3. **ViewState documentation as separate migration guide** — New PR #503 features warrant standalone docs (docs/MigrationGuides/ViewStateAndPostBack.md) rather than scattered component-by-component mentions. + +4. **User-Controls.md expansion depends on ViewState docs** — Will reference new ViewState shim patterns when complete. + +5. **Cross-linking as low-priority cleanup** — Can execute in parallel with syntax conversion work; final-pass quality improvement rather than blocker. + +6. **mkdocs.yml as final integration step** — Updated last to avoid navigation churn during other doc edits. + +**Pattern established:** All 8 issues follow consistent template (Context, Scope, Definition of Done, Notes). Labeled with `squad` + `type:docs`. Enables clear work delegation and measurable completion criteria. + +**Status:** Issues created and triaged in inbox. Awaiting team assignment. Decision note written to `.squad/decisions/inbox/forge-doc-task-plan.md`. diff --git a/.squad/agents/rogue/history.md b/.squad/agents/rogue/history.md index f9b2ee9b6..00ffb03a1 100644 --- a/.squad/agents/rogue/history.md +++ b/.squad/agents/rogue/history.md @@ -64,6 +64,8 @@ --- ## Active Decisions & Alerts +📌 **Team update (2026-03-24):** ViewState Phase 1 test coverage complete — 73 contract tests written for ViewStateDictionary and IsPostBack behavior. 3 breaking changes identified in existing tests (expected); all 2588 tests now passing. InternalsVisibleTo added for test access, EphemeralDataProtectionProvider integration verified. Phase 2 test infrastructure ready. — decided by Rogue + 📌 **Team update (2026-03-17):** HttpHandlerBase handler tests validated — 94 tests passing, 1 test fixed (HttpMethod_DefaultIsGet bad assumption). No implementation bugs found; adapter architecture verified. Commit 040fbad5 (15 files, 3218 insertions) on feature/httphandler-base. — decided by Rogue 📌 **Team update (2026-03-17):** Rogue wrote 11 bUnit tests for GUID ID rendering (#471). New RadioButton/IDRendering.razor (6 tests), enhanced CheckBox/IDRendering.razor (+3 tests). All tests pass; integrated into regression suite. — decided by Rogue @@ -365,4 +367,21 @@ Test file: `src/BlazorWebFormsComponents.Test/UpdatePanel/ContentTemplateTests.r **Team update (2026-03-20):** Middleware integration testing pattern established (TestServer + AspxRewriteMiddlewareTests.cs, 46 tests). Microsoft.AspNetCore.TestHost added to test dependencies. decided by Rogue +### ViewStateDictionary, IsPostBack & WebFormsRenderMode Contract Tests (2026-03-24) + +**73 contract tests across 3 files — all pass.** Tests written against the ViewState-PostBack-Shim-Proposal spec; validated against Cyclops's Phase 1 implementation. + +**ViewStateDictionaryTests.cs (48 tests):** Basic dictionary ops, null safety (missing key returns null not throw), type coercion, IsDirty tracking (set/add/remove/clear/MarkClean), serialization roundtrip with EphemeralDataProtectionProvider, JSON type coercion after deserialization (int/bool/string/double/DateTime), edge cases (100K strings, special chars in keys), IDictionary interface compliance, Web Forms migration pattern, LoadFrom merge. + +**IsPostBackTests.cs (14 tests):** BaseWebFormsComponent + WebFormsPageBase in Interactive (false during init, true after) and SSR (GET=false, POST=true) modes. Guard pattern (!IsPostBack) block execution tests. + +**WebFormsRenderModeTests.cs (7 tests):** Enum values, CurrentRenderMode auto-detection, IsHttpContextAvailable. + +**Key findings:** +- Existing ViewState tests will break: `ViewState_NonExistentKey_ThrowsKeyNotFoundException` (returns null now), `ViewState_HasObsoleteAttribute` ([Obsolete] removed), `IsPostBack_AlwaysReturnsFalse` (mode-adaptive now) +- bUnit 2.x: `Render()` not `RenderComponent()`; `PageService` namespace conflict requires full qualification in .cs files +- BaseWebFormsComponent sets _hasInitialized at END of OnInitializedAsync; WebFormsPageBase sets in OnInitialized +- IDataProtectionProvider must be registered for BaseWebFormsComponent rendering (EphemeralDataProtectionProvider in tests) + +**File paths:** `src/BlazorWebFormsComponents.Test/ViewStateDictionaryTests.cs`, `IsPostBackTests.cs`, `WebFormsRenderModeTests.cs` diff --git a/.squad/decisions.md b/.squad/decisions.md index d6c6b384f..da6a95810 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -12369,4 +12369,384 @@ For future Web Forms–only documentation: 2. If no features listed, create placeholder tab with BWFC component tag 3. Add note that examples are minimal/reference-only 4. These can be enhanced later with full code samples +--- + +## Merged from inbox (2026-03-24T15:30Z) + +### 2026-03-24T14:55Z: User directive +**By:** Jeffrey T. Fritz (via Copilot) +**What:** ViewState analyzers (BWFC002, BWFC020) should recommend moving away from ViewState usage, but NOT as an error — keep as Info or Warning severity. ViewState is a supported compatibility feature, not a bug. +**Why:** User request — captured for team memory + + + +### 2026-03-22T16-22-17Z: User directive +**By:** Jeffrey T. Fritz (via Copilot) +**What:** Devise a strategy to extract CSS and JS content from NuGet packages that use the old ASP.NET Web Forms BundleConfig pattern, and place them in wwwroot/ during migration. This should handle the gap where Web Forms apps reference static assets via NuGet packages (e.g., jQuery, Bootstrap) that get unpacked into Content/Scripts folders, and those references disappear when migrating to Blazor. +**Why:** User request captured for team memory. This is a real migration gap discovered during the DepartmentPortal migration: the CSS was identical but nobody thought to copy it because the delivery mechanism (NuGet + BundleConfig) is completely different in Blazor (wwwroot + CDN/libman). + + + +# Decision: ViewState Phase 1 Implementation Details + +**Author:** Cyclops +**Date:** 2026-03-24 +**Status:** Implemented on `feature/viewstate-postback-shim` + +## Context + +Implemented Phase 1 of Forge's ViewState/PostBack architecture proposal. Key implementation decisions made during build: + +## Decisions + +### 1. IDataProtectionProvider is nullable/optional +The `[Inject] private IDataProtectionProvider` on BaseWebFormsComponent is null-checked before use. If the consuming app hasn't registered Data Protection services, ViewState serialization for SSR is silently skipped. This preserves backward compatibility — existing apps that don't need SSR ViewState won't break. + +### 2. ViewState deserialization order +Deserialization from form POST happens at the TOP of `OnInitializedAsync`, BEFORE `Parent?.Controls.Add(this)`, OnInit, OnLoad, and OnPreRender events. This ensures developer code in those lifecycle methods reads correct ViewState values. Matches Web Forms behavior where ViewState was restored before Page_Load. + +### 3. CryptographicException handling +Tampered or expired ViewState payloads result in a caught `CryptographicException` that silently falls back to an empty ViewState. This is fail-safe — the component initializes with default values rather than crashing. + +### 4. Hidden field naming convention +`__bwfc_viewstate_{ID}` uses the developer-set `ID` parameter. If no ID is set, the hidden field name is `__bwfc_viewstate_` (empty suffix). Phase 2 should consider a deterministic fallback when ID is null. + +### 5. WebFormsPageBase OnInitialized override +Added `OnInitialized` override to set `_hasInitialized = true`. This is safe because WebFormsPageBase didn't previously override `OnInitialized` (it uses `OnInitializedAsync` via derived classes). The override calls `base.OnInitialized()` first. + +## Impact +- **Rogue:** Unit tests needed for ViewStateDictionary (serialize/deserialize/type coercion) and IsPostBack (SSR/Interactive modes) +- **Forge:** Phase 2 (SSR hidden field round-trip integration) can proceed +- **Beast:** ViewState docs need update — [Obsolete] removed, new behavior documented + + + +# Decision: NuGet Static Asset Migration Strategy + +**Date:** 2026-03-08 +**By:** Forge (Lead / Web Forms Reviewer) +**Status:** Proposed (awaiting Jeffrey T. Fritz approval & team review) + +--- + +## Decision + +Implement **Option C (NuGet Extraction Tool) + optional WebOptimizer** as the default migration strategy for BWFC's `bwfc migrate-assets` command. + +### What This Means + +1. **Primary Strategy:** PowerShell script that reads `packages.config`, extracts `Content/` and `Scripts/` folders from NuGet packages, places them in `wwwroot/lib/`, and generates Blazor-compatible asset references. + +2. **Intelligent CDN Mapping:** For known OSS packages (jQuery, Bootstrap, DataTables, Modernizr, SignalR, etc.), suggest CDN URLs instead of extraction to reduce wwwroot footprint. + +3. **Hybrid Default:** Extract custom/private packages, suggest CDN for OSS packages, output decision summary. + +4. **Optional Bundling:** Teams can integrate WebOptimizer or esbuild post-migration for minification + cache-busting (not required). + +--- + +## Why This Approach + +| Option | Pros | Cons | Recommendation | +|--------|------|------|---| +| **A: CDN** | Simple, no wwwroot bloat | Internet-dependent, no custom packages | ❌ Not suitable for all apps | +| **B: LibMan** | VS integrated, mixed sources | Limited to public libs, learning curve | ⚠️ Good alt for known packages | +| **C: Extraction Tool** | Works for all packages, automated, auditable | wwwroot grows, requires script maintenance | ✅ **Recommended** | +| **D: npm equivalents** | Modern ecosystem, powerful | Requires Node.js toolchain, complex setup | ⚠️ Good for modern teams | + +**Selected:** **Option C (Hybrid approach)** — Combines extraction for custom packages + CDN suggestions for known OSS, maximizing automation while respecting team preferences. + +--- + +## Implementation Details + +### New Command + +```bash +bwfc migrate-assets --source C:\MyWebFormsApp [--strategy hybrid|extract|cdn] +``` + +### Script Location + +`migration-toolkit/scripts/Migrate-NugetStaticAssets.ps1` + +### Execution Flow + +1. Parse `packages.config` → extract package IDs + versions +2. Scan `packages/` folder for `Content/` and `Scripts/` directories +3. For each detected package: + - If known OSS (in CDN map) AND strategy allows: suggest CDN, skip extraction + - Else: extract to `wwwroot/lib/{PackageName}/` +4. Generate `asset-manifest.json` (extraction summary) +5. Generate `AssetReferences.html` (copy-paste snippet) +6. Output console summary (packages extracted, CDN suggested, custom preserved) + +### Known CDN Mappings (Initial) + +- jQuery → https://code.jquery.com/ +- Bootstrap → https://stackpath.bootstrapcdn.com/bootstrap/ +- Modernizr → https://cdnjs.cloudflare.com/ +- DataTables → https://cdn.datatables.net/ +- [+10 more] + +### Output + +**Console:** +``` +✓ NuGet Static Asset Migration +======================================== +Detected 12 packages: + ✓ jQuery.3.6.0 → CDN (...) + ⓘ MyApp.Reports.1.0.0 → Extracted to wwwroot/lib/MyApp.Reports/ + +Generated Asset References: + + +... +``` + +**Files:** +- `wwwroot/lib/{PackageName}/` (extracted assets) +- `asset-manifest.json` (metadata) +- `AssetReferences.html` (snippet for App.razor) + +--- + +## Rationale + +1. **Handles all scenarios:** Works for OSS packages, custom packages, and mixed setups. +2. **Automation-ready:** Integrates into `bwfc migrate-assets` for one-command migration. +3. **Low barrier:** No Node.js, webpack, or advanced tooling required. +4. **Preserves fidelity:** Exact same assets as original Web Forms app. +5. **Auditable:** Generated manifest makes decisions transparent. +6. **Scalable:** Works for small DepartmentPortal (1 custom CSS) to enterprise apps (50+ packages). + +--- + +## DepartmentPortal Validation + +**Original (Web Forms):** +- `packages.config`: Only build tool (no static assets) +- `Content/Site.css`: Custom app stylesheet +- No external NuGet libraries + +**Migration Result:** +- `wwwroot/css/site.css` (copied) +- `asset-manifest.json`: No external packages detected +- `AssetReferences.html`: Single link tag for custom CSS + +**Outcome:** ✅ Minimal case validates extraction logic for custom assets. + +--- + +## Timeline + +- **Week 1–2:** Implement `Migrate-NugetStaticAssets.ps1` + CDN mappings +- **Week 2–3:** Integrate into `bwfc-migrate.ps1` and `bwfc` CLI +- **Week 3–4:** Documentation + performance/security guides +- **Week 4–5:** Hardening + edge case handling +- **Week 5–6:** GA release + +--- + +## Related Artifacts + +- **Strategy Document:** `dev-docs/proposals/nuget-static-asset-migration.md` +- **GitHub Issue Draft:** Issue specifications documented locally (awaiting GitHub creation by Jeffrey T. Fritz) +- **Implementation File:** `migration-toolkit/scripts/Migrate-NugetStaticAssets.ps1` (to be created) + +--- + +## Open Questions + +1. Should we support `.nupkg` file inspection (fallback if `packages/` folder unavailable)? → **Yes, add as Phase 2** +2. What's the max wwwroot size threshold before suggesting LibMan/CDN? → **No hard limit; let users decide** +3. Should we integrate WebOptimizer by default, or keep it optional? → **Optional; document as Phase 2 enhancement** +4. How to handle version mismatches (e.g., app expects Bootstrap 4.6, CDN has 5.0)? → **Exact version matching required; fail fast** + +--- + +## Approval Chain + +- [ ] Jeffrey T. Fritz (Project Owner) +- [ ] Team (Cyclops, Beast, Jubilee, Rogue) +- [ ] Implementation: Assign to Cyclops (PowerShell + toolkit integration) + +--- + +**Document Owner:** Forge +**Created:** 2026-03-08 +**Status:** Proposed + + + +# Decision: Enhanced ViewState & PostBack Shim Architecture + +**By:** Forge (Lead / Web Forms Reviewer) +**Date:** 2026-03-24 +**Status:** Proposed — Awaiting Jeffrey's Review + +## What + +Architecture proposal to upgrade ViewState and IsPostBack from compile-time stubs to working persistence mechanisms that auto-adapt to Blazor SSR and ServerInteractive rendering modes. + +## Key Decisions + +1. **ViewState becomes real:** Replace `Dictionary` with `ViewStateDictionary`. In SSR mode, round-trips via Data Protection-encrypted hidden form field. In Interactive mode, persists in component instance memory (already works). Remove `[Obsolete]`. + +2. **IsPostBack becomes mode-adaptive:** SSR → returns `true` on HTTP POST, `false` on GET. Interactive → returns `false` during OnInitialized, `true` on subsequent renders. Remove hardcoded `false`. + +3. **AutoPostBack gets real behavior:** SSR → emits `onchange="this.form.submit()"` on controls. Interactive → existing Blazor `@onchange` is already equivalent. Remove `[Obsolete]`. + +4. **IPostBackEventHandler NOT shimmed:** Too deep in Web Forms plumbing. BWFC023 analyzer continues recommending `EventCallback`. + +5. **Analyzer updates:** BWFC002/003 severity reduced to Info. BWFC020 changed to Suggestion. BWFC023 unchanged. New BWFC025 for non-serializable ViewState types. + +6. **Auto-detection, no configuration:** Uses existing `HttpContext` availability pattern. No explicit render mode configuration needed. + +## Why + +ASCX user control migration is a primary use case. The DepartmentFilter pattern (ViewState-backed properties + `!IsPostBack` guard) is universal in Web Forms codebases. Making these shims work means code-behind files migrate with zero changes — only markup needs updating. + +## Impact + +- `BaseWebFormsComponent.ViewState` type changes from `Dictionary` to `ViewStateDictionary` (implements `IDictionary`, backward compatible) +- `WebFormsPageBase.IsPostBack` changes from `=> false` to mode-adaptive property +- `[Obsolete]` removed from ViewState, IsPostBack, and AutoPostBack +- 4 analyzers updated (BWFC002, BWFC003, BWFC020 messages; new BWFC025) +- New dependency: `Microsoft.AspNetCore.DataProtection` (for ViewState encryption in SSR) + +## Estimated Effort + +7 weeks across 5 phases: Core Infrastructure (2w), SSR Persistence (2w), AutoPostBack (1w), Analyzers (1w), Docs & Samples (1w). + +## Reference + +Full proposal: `dev-docs/architecture/ViewState-PostBack-Shim-Proposal.md` + + + +# Decision: AfterDepartmentPortal Runnable Demo Setup + +**Date:** 2026-03-23 +**Author:** Jubilee (Sample Writer) +**Status:** Implemented + +## Context +AfterDepartmentPortal built clean but couldn't render — missing CSS files and no home page. + +## Decisions + +1. **Bootstrap via CDN** — Used Bootstrap 5.3.3 and Bootstrap Icons from jsdelivr CDN instead of bundling local copies. Keeps the sample lightweight and avoids checking large vendor files into the repo. + +2. **Home page at /home, not /** — Dashboard.razor already claimed `@page "/"`. Rather than disrupting the existing route, the new Home.razor welcome page lives at `/home`. The Dashboard *is* the landing page. + +3. **SectionPanel CssClass fix** — Removed `new CssClass` property that shadowed the base class `[Parameter]`. Blazor parameters are case-insensitive and must be unique across the inheritance chain. Used `OnInitialized()` to set the default instead. + +4. **Site.css copied from DepartmentPortal** — Preserves the same CSS classes used by the before/after migration pair, ensuring visual consistency. + + + +# Decision: ViewState/IsPostBack Test Coverage — Breaking Changes Identified + +**Author:** Rogue (QA Analyst) +**Date:** 2026-03-24 +**Status:** FYI — action needed by Cyclops or whoever merges the branch + +## Context + +While writing 73 contract tests for the ViewState-PostBack-Shim feature, I identified **3 existing tests that will break** due to intentional behavioral changes: + +## Breaking Tests + +1. **`WebFormsPageBase/ViewStateTests.razor` → `ViewState_NonExistentKey_ThrowsKeyNotFoundException`** + Old behavior: `Dictionary` throws on missing key. + New behavior: `ViewStateDictionary` returns `null` for missing keys (matches Web Forms semantics). + +2. **`WebFormsPageBase/ViewStateTests.razor` → `ViewState_HasObsoleteAttribute`** + Old behavior: ViewState has `[Obsolete]` attribute. + New behavior: `[Obsolete]` removed — ViewState is now a real feature. + +3. **`WebFormsPageBase/WebFormsPageBaseTests.razor` → `IsPostBack_AlwaysReturnsFalse`** + Old behavior: `IsPostBack` hardcoded to `false`. + New behavior: Mode-adaptive — returns `true` after initialization in InteractiveServer mode. + +## Recommendation + +These tests should be updated (not deleted) to reflect the new contract. My new tests in `ViewStateDictionaryTests.cs` and `IsPostBackTests.cs` already define the correct behavior. + +## Additional Notes + +- Added `InternalsVisibleTo` to main csproj for test project access to internal ViewStateDictionary members +- `IDataProtectionProvider` (via `EphemeralDataProtectionProvider`) must be registered in test contexts that render BaseWebFormsComponent-derived components — the `BlazorWebFormsTestContext` base class may need updating + + + + + +### 2026-03-24: Documentation Task Breakdown 8 GitHub Issues Created + +# Documentation Improvement Task Breakdown — Forge Decision + +**Date**: 2025-01-24 +**Context**: Post-audit follow-up to comprehensive documentation review (Beast quality pass + Forge organization/structure review) +**Source**: PR #504 (tabbed syntax template) + PR #503 (ViewState Phase 1) + documentation audit findings + +## Summary + +Decomposed remaining documentation improvement work into 8 actionable, parallelizable GitHub issues. All issues labeled `squad` + `type:docs` for triage and visibility. + +## Issues Created + +| Issue | Title | Scope | Est. LOE | +|-------|-------|-------|---------| +| #505 | Convert DataControls docs to tabbed syntax | GridView, Repeater, DataGrid, DataList, ListView, DetailsView, FormView, Chart, DataPager, PagerSettings | High (complex components) | +| #506 | Convert ValidationControls docs to tabbed syntax | BaseValidator, BaseCompareValidator, CompareValidator, RangeValidator, CustomValidator + expand stubs (RegularExpressionValidator, ValidationSummary) | Medium | +| #507 | Expand stub documentation | RegularExpressionValidator (TODO → full doc), ValidationSummary (headers only → full doc), Label.md (incomplete) | Medium | +| #508 | Document ViewState and PostBack shim features | Create ViewStateAndPostBack.md migration guide, document ViewStateDictionary, IsPostBack, hidden field persistence | Medium | +| #509 | Complete User-Controls.md migration guide | Expand with ViewState patterns, state management, PostBack handling, working examples | Medium | +| #510 | Convert EditorControls docs to tabbed syntax | RadioButton, TextBox, DropDownList, ListBox, CheckBoxList, RadioButtonList, LinkButton, ImageButton, FileUpload, HiddenField, Image, AdRotator, Calendar, BulletedList, Table, Literal, PlaceHolder, MultiView, View, Content, ContentPlaceHolder, Localize | High (large volume) | +| #511 | Add cross-linking between related components | Validation controls ↔ each other, list controls ↔ variants, data controls ↔ each other | Low (mechanical) | +| #512 | Update mkdocs.yml navigation | Add new migration guides, verify all docs indexed, no broken nav links | Low (configuration) | + +## Pattern Established + +All issues follow this template: +- **Context**: Why this matters +- **Scope**: Specific files/components affected +- **Definition of Done**: Measurable completion criteria +- **Notes**: Implementation guidance and gotchas + +## Key Decisions + +1. **Batch by component family** (EditorControls, DataControls, ValidationControls) for parallel work +2. **Expand stubs as part of syntax conversion**, not as separate work +3. **ViewState/PostBack as new migration guide**, separate from component docs +4. **Cross-linking as low-priority cleanup** (can happen in parallel with syntax conversion) +5. **mkdocs.yml kept separate** to avoid conflicts during other doc work + +## Next Steps (Team Action) + +1. Assign issues to squad members (`agent:beast` for content, `squad:forge` for review) +2. Start with EditorControls + DataControls conversions (highest volume) +3. Stub expansion (#507) can run in parallel once pattern is confirmed +4. ViewState documentation (#508) depends on PR #503 being merged; post-merge priority +5. Cross-linking (#510) is final-pass work; start after syntax conversions complete +6. mkdocs.yml (#511) should be last to avoid navigation churn during other edits + +## Related Work + +- **PR #504**: Established tabbed syntax template (Button, Panel, CheckBox as reference implementations) +- **PR #503**: ViewState Phase 1 — features now documented in #508 +- **Documentation Audit**: Identified 22+ inconsistent code blocks, missing side-by-sides, incomplete guides + +## Files Touched + +- `.squad/decisions/inbox/forge-doc-task-plan.md` (this file) — decision log +- `.squad/agents/forge/history.md` — appended learnings + +--- + +**Assigned to**: Forge (Lead Review) +**Status**: Issues created and triaged; awaiting team assignment diff --git a/.squad/decisions/inbox/copilot-directive-inline-csharp.md b/.squad/decisions/inbox/copilot-directive-inline-csharp.md new file mode 100644 index 000000000..284a0e413 --- /dev/null +++ b/.squad/decisions/inbox/copilot-directive-inline-csharp.md @@ -0,0 +1,4 @@ +### 2026-03-25T14:41Z: Inline C# in ASPX/ASCX - Coverage Gap +**By:** Jeffrey T. Fritz (via Copilot) +**What:** BWFC has no coverage or migration guidance for inline C# expressions in ASPX/ASCX pages: `<%= expression %>`, `<%# databinding %>`, `<% code blocks %>`, `<%: html-encoded %>`. This is a feature gap that needs documentation and potentially tooling support. +**Why:** User identified during docs review - many Web Forms apps use inline C# extensively and developers need migration guidance. diff --git a/.squad/orchestration-log/2026-03-24T15-05-forge.md b/.squad/orchestration-log/2026-03-24T15-05-forge.md new file mode 100644 index 000000000..dbf259a0d --- /dev/null +++ b/.squad/orchestration-log/2026-03-24T15-05-forge.md @@ -0,0 +1,54 @@ +# Orchestration Log: Forge (ViewState+PostBack Shim Architecture) + +**Spawn Date:** 2026-03-24T15:05:00Z +**Agent:** Forge (Lead / Web Forms Reviewer) +**Mode:** background +**Task:** Architecture proposal for ViewState + PostBack shim + +## Outcome + +✅ **SUCCESS** — 795-line architecture proposal produced. + +**Artifact:** `dev-docs/architecture/ViewState-PostBack-Shim-Proposal.md` + +## Key Decisions + +1. **ViewState becomes real:** Replace `Dictionary` with `ViewStateDictionary`. SSR mode uses Data Protection-encrypted hidden field round-trip. Interactive mode persists in component memory. + +2. **IsPostBack becomes mode-adaptive:** SSR → returns `true` on HTTP POST, `false` on GET. Interactive → returns `false` on OnInitialized, `true` on subsequent renders. + +3. **AutoPostBack gets real behavior:** SSR emits `onchange="this.form.submit()"`. Interactive uses existing Blazor `@onchange`. + +4. **IPostBackEventHandler NOT shimmed:** Too deep in Web Forms plumbing; recommend `EventCallback` via BWFC023. + +5. **Analyzer updates:** BWFC002/003 → Info severity. BWFC020 → Suggestion. New BWFC025 for non-serializable ViewState. + +6. **Auto-detection pattern:** Uses existing `HttpContext` availability. No explicit render mode config needed. + +## Impact + +- `BaseWebFormsComponent.ViewState` type: `Dictionary` → `ViewStateDictionary` (backward-compatible via IDictionary) +- `WebFormsPageBase.IsPostBack`: hardcoded `false` → mode-adaptive property +- Removes `[Obsolete]` from ViewState, IsPostBack, AutoPostBack +- 4 analyzers updated; new BWFC025 added +- New NuGet dependency: `Microsoft.AspNetCore.DataProtection` + +## Effort Estimate + +7 weeks across 5 phases: +- Core Infrastructure (2w) +- SSR Persistence (2w) +- AutoPostBack (1w) +- Analyzers (1w) +- Docs & Samples (1w) + +## Status + +Decision filed to team inbox (`forge-viewstate-postback-architecture.md`). Awaiting Jeffrey's review and team consensus before Cyclops + Rogue proceed with Phase 1 implementation. + +## Next Steps + +1. Jeffrey reviews proposal +2. Team discusses trade-offs +3. Cyclops begins Phase 1 (ViewStateDictionary + IsPostBack core) +4. Rogue writes unit tests in parallel diff --git a/.squad/orchestration-log/2026-03-24T15-30-coordinator.md b/.squad/orchestration-log/2026-03-24T15-30-coordinator.md new file mode 100644 index 000000000..d6ef1a3b3 --- /dev/null +++ b/.squad/orchestration-log/2026-03-24T15-30-coordinator.md @@ -0,0 +1,25 @@ +### 2026-03-24T15:30Z — ViewState Phase 1 Test Fixes & Commit + +| Field | Value | +|-------|-------| +| **Agent routed** | Coordinator (Orchestration) | +| **Why chosen** | Final phase of Phase 1 implementation — test contract updates needed before merge | +| **Mode** | `sync` | +| **Why this mode** | Test fixes are concrete, blocking commit; needed immediate verification | +| **Files authorized to read** | `src/BlazorWebFormsComponents.Test/WebFormsPageBase/ViewStateTests.razor` | +| **File(s) agent must produce** | Updated test files with correct assertions; git commit on `feature/viewstate-postback-shim` | +| **Outcome** | ✅ Completed — 2 breaking test contracts fixed (ViewState_HasObsoleteAttribute → ViewState_DoesNotHaveObsoleteAttribute, ViewState_NonExistentKey_ThrowsKeyNotFoundException → ViewState_NonExistentKey_ReturnsNull). Full test suite: 2588 passed, 0 failed. Committed as `1bf5cde5` on `feature/viewstate-postback-shim`. | + +--- + +## Summary + +Coordinator fixed the final 2 failing tests identified by Rogue's breaking change analysis: + +1. **ViewState_HasObsoleteAttribute** — Old test expected `[Obsolete]` on ViewState. Renamed to `ViewState_DoesNotHaveObsoleteAttribute` and inverted assertion (Obsolete attribute should NOT be present now that ViewState is a real feature). + +2. **ViewState_NonExistentKey_ThrowsKeyNotFoundException** — Old test expected throw on missing key. Renamed to `ViewState_NonExistentKey_ReturnsNull` and updated assertion to verify `null` return (matching Web Forms `ViewStateDictionary` semantics). + +**Result:** All 2588 tests pass, 0 failures. Phase 1 complete and ready for merge. + +**Related decision:** See `rogue-viewstate-tests.md` (breaking change analysis). diff --git a/.squad/orchestration-log/2026-03-24T15-35-forge.md b/.squad/orchestration-log/2026-03-24T15-35-forge.md new file mode 100644 index 000000000..14946bb13 --- /dev/null +++ b/.squad/orchestration-log/2026-03-24T15-35-forge.md @@ -0,0 +1,61 @@ +# Forge Orchestration Log — Documentation Task Planning + +**Date:** 2026-03-24 15:35 UTC +**Agent:** Forge +**Event:** Post-audit documentation task breakdown and GitHub issue creation + +## Summary + +Forge completed comprehensive analysis of documentation audit findings and decomposed remaining work into 8 actionable, parallelizable GitHub issues (#505–#512). All issues labeled `squad` + `type:docs` for team triage. + +## Work Completed + +### Issues Created (GitHub #505–#512) + +| Issue | Title | Component Family | LOE | +|-------|-------|------------------|-----| +| #505 | Convert DataControls docs to tabbed syntax | GridView, Repeater, DataGrid, DataList, ListView, DetailsView, FormView, Chart, DataPager, PagerSettings | High | +| #506 | Convert ValidationControls docs to tabbed syntax | BaseValidator family + stubs | Medium | +| #507 | Expand stub documentation | RegularExpressionValidator, ValidationSummary, Label | Medium | +| #508 | Document ViewState and PostBack shim features | ViewStateAndPostBack.md migration guide | Medium | +| #509 | Complete User-Controls.md migration guide | Expand with state management patterns | Medium | +| #510 | Convert EditorControls docs to tabbed syntax | 20+ editor & display controls | High | +| #511 | Add cross-linking between related components | Mechanical linking work | Low | +| #512 | Update mkdocs.yml navigation | Navigation verification & indexing | Low | + +### Key Decisions + +1. **Batch by component family** — EditorControls, DataControls, ValidationControls for parallel work +2. **Expand stubs as part of syntax conversion**, not separate work +3. **ViewState/PostBack as new migration guide**, separate from component docs +4. **Cross-linking as low-priority cleanup** — can run in parallel with syntax conversion +5. **mkdocs.yml kept separate** — prevents navigation churn during other doc work + +### Pattern Template + +All issues follow consistent template: +- **Context:** Why this work matters +- **Scope:** Specific files/components affected +- **Definition of Done:** Measurable completion criteria +- **Notes:** Implementation guidance and gotchas + +## Next Steps for Team + +1. Assign issues to squad members (`agent:beast` for content, `squad:forge` for review) +2. Start with EditorControls + DataControls conversions (highest volume) +3. Stub expansion (#507) runs in parallel once pattern confirmed +4. ViewState documentation (#508) depends on PR #503 merge +5. Cross-linking (#510) is final-pass work +6. mkdocs.yml (#511) should be last to avoid churn + +## Related PRs & Work + +- **PR #503** (feature/viewstate-postback-shim): ViewState Phase 1 — features documented in issue #508 +- **PR #504** (squad/doc-improvements): Tabbed syntax template (Button, Panel, CheckBox reference implementations) +- **Documentation Audit**: Identified 22+ inconsistent code blocks, missing side-by-sides, incomplete guides + +## Status + +✅ Decision logged +✅ Issues created and triaged +⏳ Awaiting team assignment and work commencement diff --git a/dev-docs/analysis/ASCX-Migration-Drop-In-Strategy.md b/dev-docs/analysis/ASCX-Migration-Drop-In-Strategy.md new file mode 100644 index 000000000..b60d800a9 --- /dev/null +++ b/dev-docs/analysis/ASCX-Migration-Drop-In-Strategy.md @@ -0,0 +1,1351 @@ +# ASCX → Blazor Component Migration: Drop-In Replacement Strategy Analysis + +**Analysis Date:** 2026-03-12 +**Analyst:** Forge (Web Forms Lead Reviewer) +**Case Study:** DepartmentPortal (12 ASCX controls → 12+ Blazor components) +**Objective:** Understand ASCX user control migration patterns and define a drop-in replacement playbook. + +--- + +## Executive Summary + +The DepartmentPortal migration reveals a **partial drop-in replacement strategy** where ~70% of the migration involves mechanical transformations, but significant manual steps remain. BWFC supports the Web Forms control primitives (Button, DropdownList, Repeater, etc.) but user controls require deeper architectural decisions around data binding, event handling, and component composition. + +**Key Finding:** The migration is not a true drop-in replacement. Developers must understand: +1. **Event Model Shift:** PostBack events → Blazor EventCallback parameters +2. **Data Binding Shift:** ViewState + Page_Load → Component Parameters + @code +3. **Component Composition:** ASCX Register directives → @using component includes +4. **Control Discovery:** FindControl patterns → Direct property access or cascading parameters + +--- + +## 1. ASCX Source Controls Summary + +### All 12 Controls in DepartmentPortal/Controls/ + +| Control | Type | Primary Web Forms Controls | Code-Behind Pattern | +|---------|------|---------------------------|---------------------| +| **DepartmentFilter** | Input | DropDownList, Label | AutoPostBack + event; ViewState for selected ID | +| **SearchBox** | Input | TextBox, Button | OnClick event; ViewState for text | +| **EmployeeList** | Data Grid | GridView | DataBind in Page_PreRender; paging events | +| **Pager** | Navigation | LinkButton, Repeater | Repeater binding; page change events; ViewState | +| **Breadcrumb** | Navigation | Repeater | String split binding; LINQ in Page_Load | +| **PageHeader** | Display | Literal, HtmlGenericControl | ViewState for title; Session for username | +| **AnnouncementCard** | Display | Literal (multiple) | Property-based rendering; HTML encoding | +| **QuickStats** | Display | Literal, HtmlGenericControl | Conditional visibility; PortalDataProvider calls | +| **Footer** | Display | Literal, HtmlGenericControl | ViewState for year; conditional links | +| **TrainingCatalog** | Data Grid | Repeater, Button | ItemCommand event binding; DataBind in PreRender | +| **DashboardWidget** | Container | PlaceHolder, Literal | Exposes ContentPlaceHolder property for child controls | +| **ResourceBrowser** | Composite | Repeater, LinkButton, SearchBox (nested) | Event subscription in OnInit; BindData method; nested user control events | + +### Patterns Observed + +- **8/12 controls** use ViewState for state management (DepartmentFilter, SearchBox, EmployeeList, Pager, Breadcrumb, PageHeader, Footer, QuickStats) +- **6/12 controls** declare public events (DepartmentFilter, SearchBox, Pager, TrainingCatalog, ResourceBrowser, plus implicit SelectedIndexChanged) +- **4/12 controls** use Repeater + ItemCommand pattern (Pager, TrainingCatalog, ResourceBrowser, Breadcrumb data binding) +- **3/12 controls** access PortalDataProvider directly (QuickStats, TrainingCatalog, RecentAnnouncements) +- **1/12 control** exposes a public control property (DashboardWidget.ContentPlaceHolder) for parent manipulation +- **1/12 control** subscribes to events of child user controls (ResourceBrowser subscribes to SearchBox.Search) + +--- + +## 2. Blazor Component Equivalents: Markup Comparison + +### DepartmentFilter: Drop-Down Input + +**ASCX Markup (lines 1-10):** +```html +<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="DepartmentFilter.ascx.cs" ... %> +
+ + + +
+``` + +**ASCX Code-Behind Pattern:** +- Uses **ViewState** to persist `SelectedDepartmentId` and `AutoPostBack` properties +- In `Page_Load`, populates dropdown items with `ddlDepartments.Items.Add()` +- Fires `OnSelectedIndexChanged` event which raises `DepartmentChanged` event +- Logs activity via `LogActivity()` + +**Blazor Equivalent (lines 1-18):** +```razor +
+ + +
+ +@code { + [Parameter] public EventCallback OnDepartmentChanged { get; set; } +} +``` + +**Migration Changes:** + +| Aspect | ASCX | Blazor | Diff | +|--------|------|--------|------| +| **HTML Tag** | `` | ` + + + +@code { + [Parameter] public string Placeholder { get; set; } = "Search..."; + [Parameter] public EventCallback OnSearch { get; set; } +} +``` + +**Migration Changes:** + +| Aspect | ASCX | Blazor | Diff | +|--------|------|--------|------| +| **Container** | `
` | `
` | ✅ CSS class change (Bootstrap 5) | +| **TextBox** | `` | `` | ✅ Mechanical | +| **Button** | `` | ` +} +``` + +**Pattern C: Declarative with Filtering (QuickStats, TrainingCatalog)** +```csharp +// ASCX (Code-Behind) +protected void Page_Load(object sender, EventArgs e) +{ + var courses = PortalDataProvider.GetCourses(); + if (!string.IsNullOrEmpty(CategoryFilter)) + courses = courses.Where(c => c.Category == CategoryFilter).ToList(); + rptCourses.DataSource = courses; + rptCourses.DataBind(); +} + +// Blazor (Markup) +@foreach (var course in PortalDataProvider.GetCourses().Where(c => string.IsNullOrEmpty(CategoryFilter) || c.Category == CategoryFilter)) +{ +
...
+} +``` + +**Analysis:** Blazor shifts from imperative (code-behind data binding) to declarative (markup filtering). This is generally cleaner but puts more logic in view. + +--- + +### Control Reference Pattern (FindControl) + +**Pattern:** ResourceBrowser explicitly declares protected fields for child controls: +```csharp +protected Breadcrumb ctlBreadcrumb; +protected SearchBox ctlSearchBox; +``` + +Then accesses them: +```csharp +ctlBreadcrumb.CurrentPath = "Resources"; +ctlSearchBox.Search += CtlSearchBox_Search; +``` + +**Blazor Equivalent:** +- No direct equivalent; can't "find" or reference sibling components imperatively +- Instead: Use parameters for data flow (top-down) and EventCallback for events (bottom-up) +- Alternative: Use service injection for shared state + +**Migration Gap:** Deep component coordination (Resource browser controls Breadcrumb.CurrentPath; subscribes to SearchBox.Search) requires architectural rethinking in Blazor. + +--- + +## 5. BWFC Coverage Analysis + +### Controls Used in DepartmentPortal ASCX Files + +| Web Forms Control | Frequency | BWFC Status | Notes | +|------------------|-----------|-------------|-------| +| `` | 1 | ✅ Available | DepartmentFilter; renders as `` | +| `` | 2 | ✅ Available | SearchBox, TrainingCatalog; renders as ` + ``` + +--- + +### Phase 5: Convert Data Binding (Manual - 20-30 minutes) + +**Pattern A: Simple Data Binding** +```csharp +// ASCX Code-Behind +var departments = PortalDataProvider.GetDepartments(); +ddlDepartments.DataSource = departments; +ddlDepartments.DataBind(); + +// Blazor Markup +@foreach (var dept in PortalDataProvider.GetDepartments()) +{ + +} +``` + +**Pattern B: Filtered Collection with Conditional Logic** +```csharp +// ASCX Code-Behind +var data = Employees; +if (!string.IsNullOrEmpty(DepartmentFilter)) + data = data.Where(e => e.Department == DepartmentFilter).ToList(); +gvEmployees.DataSource = data; +gvEmployees.DataBind(); + +// Blazor Markup +@foreach (var emp in GetFilteredEmployees()) +{ + + @emp.Name + ... + +} + +@code { + private IEnumerable GetFilteredEmployees() + { + var data = Employees ?? []; + if (!string.IsNullOrEmpty(DepartmentFilter)) + data = data.Where(e => e.Department == DepartmentFilter); + return data; + } +} +``` + +**Pattern C: Repeater with ItemCommand Events** +```csharp +// ASCX + + + + + + +protected void rptPages_ItemCommand(object source, RepeaterCommandEventArgs e) +{ + if (e.CommandName == "SelectPage") + { + int page = int.Parse(e.CommandArgument.ToString()); + OnPageChanged(page); + } +} + +// Blazor +@foreach (int page in GetPages()) +{ + +} +``` + +--- + +### Phase 6: Handle Composite Controls (Manual/Architectural - 30-60 minutes) + +**Case: Parent Control Accessing Child Controls** + +**ASCX Pattern (Imperative):** +```csharp +protected SearchBox ctlSearchBox; +protected override void OnInit(EventArgs e) +{ + base.OnInit(e); + ctlSearchBox.Search += OnChildSearch; +} +``` + +**Blazor Pattern (Declarative):** +```razor + + +@code { + private string searchTerm = string.Empty; + + private async Task HandleSearch() + { + // Parent decides what to do + await OnSearch.InvokeAsync(searchTerm); + } +} +``` + +**Key Change:** Child events don't automatically flow to parent. Parent must explicitly provide handlers and state. + +--- + +### Phase 7: Testing & Validation (Manual - 20-30 minutes per control) + +**Checklist:** + +- [ ] Component renders without errors +- [ ] Parameters accept values from parent +- [ ] Events fire and parent receives callbacks +- [ ] Data displays correctly (compare HTML structure to original) +- [ ] CSS classes intact; styling matches +- [ ] Accessibility: labels, aria-* attributes present +- [ ] No console errors (JavaScript or .NET) +- [ ] Manual browser test: click buttons, change dropdowns, verify behavior + +**Deliverable:** QA Sign-off + +--- + +## 8. Proposed Drop-In Replacement Playbook Summary + +### Myth vs Reality + +**Myth:** "ASCX controls are drop-in replacements for Blazor components. Just remove `asp:` prefixes." + +**Reality:** ~70% of the work is mechanical; ~30% requires architectural understanding of Blazor's component model. + +### The Real Drop-In Replacement Strategy + +#### **Tier 1: Mechanical (Can be Automated)** +- ✅ Remove `<%@ Control ... %>` declaration +- ✅ Replace ``, ``, ``, `` with HTML or BWFC components +- ✅ Convert `` to `@foreach` +- ✅ Convert `<%@ Register %>` to `@using` + +**Time: 5-10 minutes per control (could be scripted)** + +#### **Tier 2: Manual-Parameter Conversion (Requires Understanding)** +- ⚠️ Replace ViewState properties with `[Parameter]` properties +- ⚠️ Replace `OnPropertyChanged` patterns with `EventCallback` parameters +- ⚠️ Remove `AutoPostBack` (no equivalent); add explicit `@onchange` or `@onclick` handlers +- ⚠️ Flatten custom `EventArgs` types to individual parameters + +**Time: 15-20 minutes per control** + +#### **Tier 3: Architectural Decisions (Requires Design Thinking)** +- 🔴 Composite Controls: Redesign how parent controls access/coordinate children +- 🔴 Data-Bound Controls: Choose between BWFC data controls or manual rendering +- 🔴 State Management: Decide on parent-owned vs component-owned state for complex interactions +- 🔴 Logging/Services: Wire up dependency injection for services referenced in code-behind + +**Time: 30-60 minutes per control (or skip if features not needed)** + +### Critical Success Factors + +1. **Parent Ownership:** In Blazor, the parent component owns state and events. Controls are passive (receive parameters, invoke callbacks). This is the biggest paradigm shift. + +2. **No Imperative Control Access:** Cannot call methods on child controls or access properties imperatively (no FindControl). Use parameters and EventCallback instead. + +3. **Event Data Flattening:** Custom EventArgs types don't work. Pass individual parameters or tuple types. + +4. **Async-First:** Event handlers are async (`EventCallback`). Use `await` when invoking. + +5. **HTML Generation:** Move away from control-based HTML generation (GridView columns, Repeater ItemTemplate) to explicit `@foreach` + markup. + +--- + +## Appendix: Recommended Tooling / Automation Opportunities + +### Low-Hanging Fruit for Automation + +1. **Register Directive → @using Converter** + - Input: `<%@ Register Src="~/Controls/SearchBox.ascx" TagPrefix="uc" TagName="SearchBox" %>` + - Output: `@using Components.Shared` + Razor markup: `` + +2. **Web Forms Control → HTML/BWFC Mapper** + - Input: `` + - Output: `` + - Handles: TextBox, Button, Label, Literal, DropDownList, CheckBox, RadioButton, LinkButton + +3. **ViewState Property Extractor** + - Input: Code-behind file + - Output: List of ViewState-backed properties with suggested `[Parameter]` signatures + - Example: + ```csharp + // Extract: + public string SearchText { get { return (string)ViewState["SearchText"]; } ... } + // Generate: + [Parameter] public string SearchText { get; set; } = string.Empty; + [Parameter] public EventCallback OnSearchTextChanged { get; set; } + ``` + +4. **Event Handler Signature Converter** + - Input: `public event EventHandler DepartmentChanged;` + - Output: `[Parameter] public EventCallback OnDepartmentChanged { get; set; }` + - Handles: Single-type events; warns on custom EventArgs + +5. **DataBind() → @foreach Converter** + - Input: Code-behind with Repeater.DataBind() call + - Output: Razor markup with `@foreach` + - Includes: ItemTemplate expression conversion + +### Medium Complexity + +6. **Nested Control Event Bridge Generator** + - Input: Control code-behind referencing `protected ChildControl ctlChild;` + - Output: Suggested Blazor parameter signatures and EventCallback handlers + - Flag: Architectural decision required + +7. **GridView → Blazor Table Generator** + - Input: `` with `` columns + - Output: Choice of (A) BWFC GridView or (B) HTML table with `@foreach` + - Note: Requires understanding of AllowPaging, AllowSorting, OnPageIndexChanging, etc. + +### No Quick Wins + +8. **PlaceHolder Content Injection Converter** + - Input: Code accessing `ContentPlaceHolder.Controls.Add(...)` + - Output: Blazor `@ChildContent` RenderFragment + - Complexity: Architectural; no mechanical conversion + +--- + +## Conclusion + +The ASCX → Blazor migration is **70% mechanical, 30% architectural**. BWFC provides the primitives (Button, Label, TextBox, etc.), but user control migration requires: + +1. **Understanding Blazor's parameter-driven model** vs Web Forms' event-driven model +2. **Flattening object hierarchies** (nested controls, custom EventArgs) +3. **Shifting state management** from server-side ViewState to component parameters +4. **Inverting control flow** (parent-driven data and events, not child-driven) + +**Best practices for drop-in replacement:** +- Focus on Tier 1 (mechanical) first—candidate for scripting +- Accept Tier 2 (parameters/events) as necessary manual work—15-20 min per control +- Plan Tier 3 (composite, data-bound, service-integrated) controls separately with stakeholder input + +**Recommendation:** Create a **BWFC User Control Migration Guide** with step-by-step examples (using DepartmentPortal as case study), automated tooling for Tier 1 conversion, and architectural decision trees for Tier 3 patterns. + +--- + +*Analysis Complete: 2026-03-12* diff --git a/dev-docs/architecture/ViewState-PostBack-Shim-Proposal.md b/dev-docs/architecture/ViewState-PostBack-Shim-Proposal.md new file mode 100644 index 000000000..135fe6981 --- /dev/null +++ b/dev-docs/architecture/ViewState-PostBack-Shim-Proposal.md @@ -0,0 +1,794 @@ +# Enhanced ViewState & PostBack Shim — Architecture Proposal + +**Author:** Forge (Lead / Web Forms Reviewer) +**Date:** 2026-03-24 +**Status:** Proposal — Awaiting Jeffrey's Review +**Requested by:** Jeffrey T. Fritz + +--- + +## Executive Summary + +The current ViewState and IsPostBack implementations in BlazorWebFormsComponents are compile-time stubs: ViewState is an in-memory `Dictionary` marked `[Obsolete]`, and `IsPostBack` is hardcoded to `false`. These stubs allow migrated code to *compile*, but they don't *behave correctly* — Web Forms code that relied on ViewState persistence or PostBack detection silently produces wrong results. + +This proposal upgrades both features from "compiles but doesn't work" to "compiles AND works correctly" across both Blazor SSR and ServerInteractive rendering modes. The goal: **a Web Forms developer's ViewState-backed property pattern and `if (!IsPostBack)` guard should work unchanged in migrated code-behind**. + +--- + +## Table of Contents + +1. [Enhanced ViewState](#1-enhanced-viewstate) +2. [PostBack Shim](#2-postback-shim) +3. [Rendering Mode Awareness](#3-rendering-mode-awareness) +4. [Migration Impact](#4-migration-impact) +5. [API Surface Proposal](#5-api-surface-proposal) +6. [Risks & Trade-offs](#6-risks--trade-offs) +7. [Implementation Roadmap](#7-implementation-roadmap) + +--- + +## 1. Enhanced ViewState + +### 1.1 The Problem + +Web Forms ViewState serialized control state into a hidden `__VIEWSTATE` field on every form POST. Developers used it constantly: + +```csharp +// Classic Web Forms pattern — used in thousands of ASCX controls +public int SelectedDepartmentId +{ + get { object val = ViewState["SelectedDepartmentId"]; return val != null ? (int)val : 0; } + set { ViewState["SelectedDepartmentId"] = value; } +} +``` + +Today in BWFC, this compiles but: +- The dictionary is in-memory only — values vanish on navigation +- In SSR mode, the dictionary is re-created on every request — values don't survive form POST +- The `[Obsolete]` warning tells developers to stop using it, but the migration path requires them to manually convert every ViewState-backed property to `[Parameter]` + +### 1.2 Design: Mode-Adaptive ViewState + +ViewState should behave differently based on rendering mode, matching the semantics that Web Forms developers expect: + +| Mode | Persistence Mechanism | Lifetime | How It Works | +|------|----------------------|----------|--------------| +| **ServerInteractive** | Component instance memory | Circuit lifetime | Already works today — the dictionary lives as long as the component. No change needed. | +| **SSR (Static)** | Hidden form field (`__bwfc_viewstate`) | Request → Response → Next Request | Serialized to a protected hidden field on render, deserialized on form POST. Mirrors original Web Forms behavior. | + +### 1.3 ServerInteractive Mode — No Changes Needed + +In ServerInteractive mode, the Blazor component instance lives on the server for the duration of the SignalR circuit. The existing `Dictionary` already persists across re-renders. ViewState-backed properties **already work correctly** in this mode. + +The only change: **remove the `[Obsolete]` attribute**. + +### 1.4 SSR Mode — Hidden Field Persistence + +In SSR mode, each HTTP request creates a new component instance. ViewState must round-trip through the form, exactly as Web Forms did. + +**Mechanism:** + +1. **On Render:** Serialize the ViewState dictionary → encrypt/sign with `IDataProtector` → emit as `` +2. **On Form POST:** Deserialize the incoming hidden field → populate the ViewState dictionary before `OnInitialized` runs → developer code reads correct values + +**Why `IDataProtector` and not raw serialization:** +Web Forms ViewState was infamously vulnerable to tampering until `ViewStateMAC` became mandatory in .NET 4.5.2. We should be secure by default — ASP.NET Core's Data Protection API handles key rotation, encryption, and anti-tampering. + +**Serialization format:** JSON via `System.Text.Json`. Web Forms used `LosFormatter`/`ObjectStateFormatter` (binary). JSON is debuggable, smaller for typical use cases, and aligns with modern .NET. + +**Type safety concern:** Web Forms ViewState stored `object` values requiring casts. We should support the same `object`-based API for migration compatibility, but also offer a type-safe overlay: + +```csharp +// Migration-compatible (unchanged from Web Forms code-behind): +public int SelectedDepartmentId +{ + get { object val = ViewState["SelectedDepartmentId"]; return val != null ? (int)val : 0; } + set { ViewState["SelectedDepartmentId"] = value; } +} + +// NEW: Type-safe convenience (optional, for developers who want to improve their code): +public int SelectedDepartmentId +{ + get => ViewState.GetValueOrDefault("SelectedDepartmentId"); + set => ViewState.Set("SelectedDepartmentId", value); +} +``` + +### 1.5 ViewState Location Decision + +**Recommendation: Keep ViewState on `BaseWebFormsComponent`.** + +Rationale: +- It's already there and thousands of migrated code-behinds reference `ViewState` as an instance member +- Moving it to a service would break the `this.ViewState["key"]` syntax that Web Forms code uses directly +- `WebFormsPageBase` should also keep its own `ViewState` property for page-level state (it already has one) + +**Do NOT extract to a separate service.** The whole point is migration-compatibility — `ViewState["key"]` must resolve on `this` without any DI or constructor changes. + +### 1.6 The `[Obsolete]` Question + +**Remove `[Obsolete]` from ViewState once this ships.** It's no longer a stub — it's a real feature. The obsolete message `"ViewState is supported for compatibility and is discouraged for future use"` becomes misleading once ViewState actually works. + +**BUT:** Add a code comment explaining that ViewState is a migration shim, not a recommended pattern for new Blazor code: + +```csharp +/// +/// Dictionary-based state storage emulating ASP.NET Web Forms ViewState. +/// In ServerInteractive mode, persists for the component's lifetime. +/// In SSR mode, round-trips via a protected hidden form field. +/// +/// Migration note: This enables Web Forms ViewState-backed property +/// patterns to work unchanged. For new Blazor code, prefer [Parameter] properties +/// and component fields. +/// +public ViewStateDictionary ViewState { get; } +``` + +### 1.7 ViewStateDictionary — Enhanced Type + +Replace `Dictionary` with a custom `ViewStateDictionary` that: + +1. Implements `IDictionary` (backward-compatible) +2. Adds type-safe convenience methods +3. Tracks dirty state for serialization optimization +4. Handles JSON deserialization type coercion (JSON numbers → int/long/double as needed) + +```csharp +public class ViewStateDictionary : IDictionary +{ + private readonly Dictionary _store = new(); + + // Migration-compatible indexer (unchanged Web Forms syntax) + public object this[string key] + { + get => _store.TryGetValue(key, out var value) ? value : null; + set { _store[key] = value; IsDirty = true; } + } + + // Type-safe convenience methods (new) + public T GetValueOrDefault(string key, T defaultValue = default) + { + if (!_store.TryGetValue(key, out var value) || value is null) + return defaultValue; + + // Handle JSON deserialization type coercion + if (value is JsonElement element) + return element.Deserialize(); + + return (T)Convert.ChangeType(value, typeof(T)); + } + + public void Set(string key, T value) + { + _store[key] = value; + IsDirty = true; + } + + // Serialization support + internal bool IsDirty { get; private set; } + internal void MarkClean() => IsDirty = false; + + internal string Serialize(IDataProtector protector) + { + var json = JsonSerializer.Serialize(_store); + return protector.Protect(json); + } + + internal static ViewStateDictionary Deserialize(string protectedPayload, IDataProtector protector) + { + var json = protector.Unprotect(protectedPayload); + var dict = new ViewStateDictionary(); + var values = JsonSerializer.Deserialize>(json); + foreach (var kvp in values) + dict._store[kvp.Key] = kvp.Value; // Store as JsonElement for lazy type coercion + return dict; + } + + // IDictionary implementation delegated to _store... +} +``` + +--- + +## 2. PostBack Shim + +### 2.1 The Problem + +Web Forms developers universally wrote: + +```csharp +protected void Page_Load(object sender, EventArgs e) +{ + if (!IsPostBack) + { + // Bind data, initialize controls — only on first load + BindDepartments(); + } +} +``` + +Today, `IsPostBack` is hardcoded to `false`. The guarded block always executes. This is *accidentally correct* for initial renders but wrong for form submissions in SSR mode — the developer intended to skip re-binding on postback. + +### 2.2 Design: Mode-Adaptive IsPostBack + +| Mode | `IsPostBack` Behavior | Rationale | +|------|----------------------|-----------| +| **SSR — GET request** | `false` | Initial page load. Same as Web Forms first-load. | +| **SSR — POST request** | `true` | Form submission. This IS a postback. Exactly matches Web Forms semantics. | +| **ServerInteractive — `OnInitialized`** | `false` | First render of the component. Matches Page_Load on initial GET. | +| **ServerInteractive — subsequent renders** | `true` | After first render, any re-render is triggered by user interaction — conceptually a postback. | + +### 2.3 SSR Implementation + +In SSR mode, `HttpContext` is available. We can check the HTTP method: + +```csharp +// In WebFormsPageBase (and BaseWebFormsComponent) +public bool IsPostBack +{ + get + { + // SSR mode: HttpContext is available + if (_httpContextAccessor?.HttpContext is { } context) + return HttpMethods.IsPost(context.Request.Method); + + // ServerInteractive mode: track initialization state + return _hasInitialized; + } +} +``` + +This directly mirrors Web Forms: a form submission (`POST`) is a postback; a navigation (`GET`) is not. + +### 2.4 ServerInteractive Implementation + +In ServerInteractive mode, there's no HTTP request on re-renders. We use component lifecycle: + +```csharp +private bool _hasInitialized; + +protected override void OnInitialized() +{ + base.OnInitialized(); + // After OnInitialized completes, subsequent renders are "postbacks" + _hasInitialized = true; +} +``` + +This means: +- During `OnInitialized` → `IsPostBack == false` (first load) +- During `OnParametersSet` on first render → `IsPostBack == false` (still first load) +- After `OnInitialized` completes, any subsequent event-driven render → `IsPostBack == true` + +**Key insight:** In Web Forms, `Page_Load` fires on every request. The `!IsPostBack` guard prevents re-initialization on postbacks. In Blazor ServerInteractive, `OnInitialized` already only fires once, so the `!IsPostBack` guard inside `OnInitialized` is redundant but harmless. The real value is in `OnParametersSet`, which fires on every render — here, `IsPostBack` correctly distinguishes first render from subsequent parameter changes. + +### 2.5 AutoPostBack — Actual Behavior + +`AutoPostBack` in Web Forms meant: "when the user changes this control's value, automatically submit the form to the server." + +| Mode | AutoPostBack Behavior | +|------|----------------------| +| **SSR** | Emit JavaScript `onchange="this.form.submit()"` on the rendered ``. This causes a real form POST, which the server handles as a new request. | +| **ServerInteractive** | Already the default behavior — Blazor's `@onchange` fires immediately over SignalR. `AutoPostBack` is redundant but should be respected. | + +**Implementation for SSR:** + +```razor +@* In DropDownList.razor *@ + +``` + +**Better approach — avoid inline ` + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ +

404 - Not found

+ +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/Accordion/index.html b/site/AjaxToolkit/Accordion/index.html new file mode 100644 index 000000000..fdc28785c --- /dev/null +++ b/site/AjaxToolkit/Accordion/index.html @@ -0,0 +1,5441 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Accordion - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Accordion

+

The Accordion displays a set of collapsible content panes arranged vertically. Only one pane is expanded at a time, allowing users to navigate between sections without leaving the page. The companion AccordionPane component defines each header/content pair within the Accordion.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/Accordion

+

Features Supported in Blazor

+
    +
  • SelectedIndex — Zero-based index of the currently expanded pane
    • +
  • SelectedIndexChanged — Event raised when the selected pane changes
    • +
  • FadeTransitions — Whether to use fade transitions when switching panes
    • +
  • TransitionDuration — Duration of expand/collapse animations in milliseconds
    • +
  • HeaderCssClass — CSS class applied to each pane header div
    • +
  • ContentCssClass — CSS class applied to each pane content div
    • +
  • RequireOpenedPane — Whether at least one pane must always be open
    • +
  • AutoSize — How pane content areas are automatically sized
    • +
  • SuppressHeaderPostbacks — Whether header clicks suppress postback behavior
    • +
  • CssClass — CSS class applied to the outer Accordion container div
    • +
  • ChildContent — Contains AccordionPane child components
    • +
+

AccordionPane Parameters

+
    +
  • Header — RenderFragment for the clickable header content
    • +
  • Content — RenderFragment for the collapsible body content
    • +
+

AutoSize Enum

+

Controls how pane content areas are sized:

+
enum AutoSizeMode
+{
+    None = 0,   // No automatic sizing (default)
+    Fill = 1,   // Content areas fill available space
+    Limit = 2   // Content areas are limited to a maximum size
+}
+
+

Web Forms Syntax

+
<ajaxToolkit:Accordion
+    ID="acc1"
+    runat="server"
+    SelectedIndex="0"
+    FadeTransitions="true"
+    TransitionDuration="300"
+    HeaderCssClass="accordionHeader"
+    ContentCssClass="accordionContent"
+    RequireOpenedPane="true"
+    AutoSize="None"
+    SuppressHeaderPostbacks="true">
+    <Panes>
+        <ajaxToolkit:AccordionPane>
+            <Header>Section 1</Header>
+            <Content>
+                <p>Content for section 1.</p>
+            </Content>
+        </ajaxToolkit:AccordionPane>
+        <ajaxToolkit:AccordionPane>
+            <Header>Section 2</Header>
+            <Content>
+                <p>Content for section 2.</p>
+            </Content>
+        </ajaxToolkit:AccordionPane>
+    </Panes>
+</ajaxToolkit:Accordion>
+
+

Blazor Migration

+
<Accordion
+    SelectedIndex="0"
+    FadeTransitions="true"
+    TransitionDuration="300"
+    HeaderCssClass="accordionHeader"
+    ContentCssClass="accordionContent"
+    RequireOpenedPane="true"
+    AutoSize="AutoSizeMode.None"
+    SuppressHeaderPostbacks="true">
+    <AccordionPane>
+        <Header>Section 1</Header>
+        <Content>
+            <p>Content for section 1.</p>
+        </Content>
+    </AccordionPane>
+    <AccordionPane>
+        <Header>Section 2</Header>
+        <Content>
+            <p>Content for section 2.</p>
+        </Content>
+    </AccordionPane>
+</Accordion>
+
+

Migration is simple: Remove the ajaxToolkit: prefix, remove runat="server" and ID, and replace the <Panes> wrapper with direct <AccordionPane> children. Everything else stays the same!

+

Properties Reference

+

Accordion

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
SelectedIndexint0Zero-based index of the currently expanded pane. Set to -1 for no expanded pane (only valid when RequireOpenedPane is false)
SelectedIndexChangedEventCallback<int>—Raised when the selected pane index changes
FadeTransitionsboolfalseWhether to use fade transitions when switching panes
TransitionDurationint300Duration of expand/collapse animations in milliseconds
HeaderCssClassstring""CSS class applied to each pane header div
ContentCssClassstring""CSS class applied to each pane content div
RequireOpenedPanebooltrueWhether at least one pane must always be open
AutoSizeAutoSizeModeNoneHow pane content areas are automatically sized
SuppressHeaderPostbacksbooltrueWhether header clicks suppress postback behavior
CssClassstring""CSS class applied to the outer Accordion container div
+

AccordionPane

+ + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
HeaderRenderFragment—The header content rendered inside the clickable header div
ContentRenderFragment—The body content rendered inside the collapsible content div
+

Usage Examples

+

Basic Accordion

+
@rendermode InteractiveServer
+
+<Accordion SelectedIndex="0" HeaderCssClass="acc-header" ContentCssClass="acc-content">
+    <AccordionPane>
+        <Header>Getting Started</Header>
+        <Content>
+            <p>Welcome! This section covers the basics.</p>
+        </Content>
+    </AccordionPane>
+    <AccordionPane>
+        <Header>Advanced Topics</Header>
+        <Content>
+            <p>Dig deeper into advanced features.</p>
+        </Content>
+    </AccordionPane>
+    <AccordionPane>
+        <Header>FAQ</Header>
+        <Content>
+            <p>Frequently asked questions and answers.</p>
+        </Content>
+    </AccordionPane>
+</Accordion>
+
+<style>
+    .acc-header {
+        background: #333; color: white; padding: 10px 15px;
+        border-bottom: 1px solid #555; font-weight: bold;
+    }
+    .acc-content { padding: 15px; background: #f9f9f9; }
+</style>
+
+

Accordion with Fade Transitions

+
@rendermode InteractiveServer
+
+<Accordion
+    SelectedIndex="0"
+    FadeTransitions="true"
+    TransitionDuration="500"
+    HeaderCssClass="fade-header"
+    ContentCssClass="fade-content">
+    <AccordionPane>
+        <Header>📋 Details</Header>
+        <Content><p>Detailed information here.</p></Content>
+    </AccordionPane>
+    <AccordionPane>
+        <Header>📊 Statistics</Header>
+        <Content><p>Key metrics and data.</p></Content>
+    </AccordionPane>
+</Accordion>
+
+

Accordion with All-Collapsed Support

+

When RequireOpenedPane is false, clicking the selected pane header collapses it:

+
@rendermode InteractiveServer
+
+<Accordion
+    SelectedIndex="-1"
+    RequireOpenedPane="false"
+    HeaderCssClass="toggle-header"
+    ContentCssClass="toggle-content"
+    SelectedIndexChanged="OnPaneChanged">
+    <AccordionPane>
+        <Header>Optional Section A</Header>
+        <Content><p>This pane can be collapsed.</p></Content>
+    </AccordionPane>
+    <AccordionPane>
+        <Header>Optional Section B</Header>
+        <Content><p>This pane can also be collapsed.</p></Content>
+    </AccordionPane>
+</Accordion>
+
+<p>Selected index: @currentIndex</p>
+
+@code {
+    private int currentIndex = -1;
+
+    void OnPaneChanged(int index)
+    {
+        currentIndex = index;
+    }
+}
+
+

HTML Output

+

The Accordion renders an outer <div> container with class ajax__accordion plus any custom CssClass. Each AccordionPane renders:

+
<div id="..." class="ajax__accordion accordionClass">
+    <!-- Pane 1 -->
+    <div id="..." class="ajax__accordion_header headerClass" role="tab"
+         aria-selected="true" aria-expanded="true" style="cursor:pointer;">
+        Section 1
+    </div>
+    <div id="..." class="ajax__accordion_content contentClass" role="tabpanel">
+        <p>Content for section 1.</p>
+    </div>
+
+    <!-- Pane 2 (collapsed) -->
+    <div id="..." class="ajax__accordion_header headerClass" role="tab"
+         aria-selected="false" aria-expanded="false" style="cursor:pointer;">
+        Section 2
+    </div>
+    <div id="..." class="ajax__accordion_content contentClass" role="tabpanel"
+         style="display:none;overflow:hidden;">
+        <p>Content for section 2.</p>
+    </div>
+</div>
+
+

JavaScript Interop

+

The Accordion loads accordion.js as an ES module on first render. JavaScript handles:

+
    +
  • Smooth slide/fade animations when switching panes
    • +
  • initAccordion() — Initializes the accordion with configuration options
    • +
  • selectPane() — Animates the transition between panes
    • +
  • disposeAccordion() — Cleans up resources on disposal
    • +
+

Render Mode Requirements

+

The Accordion requires InteractiveServer render mode for animated transitions:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The Accordion renders the correct HTML structure (selected pane visible, others hidden), but animated transitions won't work. Clicking headers still toggles panes via Blazor server events.
    • +
  • JavaScript disabled: Same as SSR — pane switching works but without animation.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:Accordion
++ <Accordion
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Remove <Panes> wrapper — Place <AccordionPane> elements directly inside <Accordion>

    +
    4. +
  4. +

    Update enum references — Use AutoSizeMode.None instead of "None"

    +
    5. +
+

Before (Web Forms)

+
<ajaxToolkit:Accordion ID="acc1" runat="server"
+    SelectedIndex="0" RequireOpenedPane="true"
+    HeaderCssClass="header" ContentCssClass="content">
+    <Panes>
+        <ajaxToolkit:AccordionPane>
+            <Header>Section 1</Header>
+            <Content><p>Content 1</p></Content>
+        </ajaxToolkit:AccordionPane>
+    </Panes>
+</ajaxToolkit:Accordion>
+
+

After (Blazor)

+
<Accordion SelectedIndex="0" RequireOpenedPane="true"
+    HeaderCssClass="header" ContentCssClass="content">
+    <AccordionPane>
+        <Header>Section 1</Header>
+        <Content><p>Content 1</p></Content>
+    </AccordionPane>
+</Accordion>
+
+

Best Practices

+
    +
  1. Use descriptive headers — Help users scan section titles quickly
    2. +
  2. Keep pane content focused — Each pane should cover one topic or section
    3. +
  3. Provide visual feedback — Style active headers differently from inactive ones
    4. +
  4. Consider default selection — Start with the most relevant pane expanded
    5. +
  5. Accessibility — Headers use role="tab" and aria-expanded automatically
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
No panes visibleVerify SelectedIndex is within range (0 to pane count - 1). Check that AccordionPane components are direct children of Accordion.
Animation not workingEnsure @rendermode InteractiveServer is set. Check browser console for JavaScript errors.
All panes collapsed unexpectedlyIf RequireOpenedPane="false", clicking the active pane collapses it. Set RequireOpenedPane="true" if one pane must always be open.
AccordionPane throws exceptionAccordionPane must be inside an Accordion component. Verify the nesting structure.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/AlwaysVisibleControlExtender/index.html b/site/AjaxToolkit/AlwaysVisibleControlExtender/index.html new file mode 100644 index 000000000..714292920 --- /dev/null +++ b/site/AjaxToolkit/AlwaysVisibleControlExtender/index.html @@ -0,0 +1,5315 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AlwaysVisibleControlExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

AlwaysVisibleControlExtender

+

The AlwaysVisibleControlExtender keeps a control visible in a fixed position on the screen even when the user scrolls the page. This is useful for floating toolbars, help buttons, notification areas, or sticky navigation elements that should remain accessible at all times.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/AlwaysVisibleControlExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the element to keep visible
    • +
  • HorizontalOffset — Pixels from the horizontal edge
    • +
  • VerticalOffset — Pixels from the vertical edge
    • +
  • HorizontalSide — Which horizontal edge (Left, Center, Right)
    • +
  • VerticalSide — Which vertical edge (Top, Middle, Bottom)
    • +
  • ScrollEffectDuration — Animation duration in seconds
    • +
  • UseAnimation — Whether to animate position changes
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

HorizontalSide Enum

+

Controls horizontal positioning:

+
enum HorizontalSide
+{
+    Left = 0,
+    Center = 1,
+    Right = 2
+}
+
+

VerticalSide Enum

+

Controls vertical positioning:

+
enum VerticalSide
+{
+    Top = 0,
+    Middle = 1,
+    Bottom = 2
+}
+
+

Web Forms Syntax

+
<asp:Panel ID="pnlHelp" runat="server" style="width: 250px; padding: 10px; background-color: #e3f2fd; border: 1px solid #1976d2;">
+    <strong>Need Help?</strong>
+    <p>Click here to get started.</p>
+</asp:Panel>
+
+<ajaxToolkit:AlwaysVisibleControlExtender
+    ID="sticky1"
+    runat="server"
+    TargetControlID="pnlHelp"
+    HorizontalSide="Right"
+    VerticalSide="Bottom"
+    HorizontalOffset="20"
+    VerticalOffset="20"
+    UseAnimation="true"
+    ScrollEffectDuration="0.1" />
+
+

Blazor Migration

+
<Panel ID="pnlHelp" style="width: 250px; padding: 10px; background-color: #e3f2fd; border: 1px solid #1976d2;">
+    <strong>Need Help?</strong>
+    <p>Click here to get started.</p>
+</Panel>
+
+<AlwaysVisibleControlExtender
+    TargetControlID="pnlHelp"
+    HorizontalSide="HorizontalSide.Right"
+    VerticalSide="VerticalSide.Bottom"
+    HorizontalOffset="20"
+    VerticalOffset="20"
+    UseAnimation="true"
+    ScrollEffectDuration="0.1" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Use enum type names for positioning!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the element to keep visible
HorizontalOffsetint0Number of pixels from the horizontal edge
VerticalOffsetint0Number of pixels from the vertical edge
HorizontalSideHorizontalSideLeftWhich horizontal edge to position against (Left, Center, Right)
VerticalSideVerticalSideTopWhich vertical edge to position against (Top, Middle, Bottom)
ScrollEffectDurationfloat0.1Duration of the position animation in seconds
UseAnimationbooltrueWhether to animate position changes smoothly
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Sticky Help Button (Bottom-Right)

+
@rendermode InteractiveServer
+
+<Panel ID="pnlHelp" style="width: 200px; padding: 15px; background-color: #4CAF50; color: white; border-radius: 5px; cursor: pointer;">
+    <strong>?</strong> Need Help?
+</Panel>
+
+<AlwaysVisibleControlExtender
+    TargetControlID="pnlHelp"
+    HorizontalSide="HorizontalSide.Right"
+    VerticalSide="VerticalSide.Bottom"
+    HorizontalOffset="15"
+    VerticalOffset="15"
+    UseAnimation="true" />
+
+ +
@rendermode InteractiveServer
+
+<Panel ID="pnlNav" style="width: 100%; padding: 10px; background-color: #333; color: white;">
+    <a href="#" style="color: white; margin-right: 20px;">Home</a>
+    <a href="#" style="color: white; margin-right: 20px;">Products</a>
+    <a href="#" style="color: white; margin-right: 20px;">Contact</a>
+</Panel>
+
+<AlwaysVisibleControlExtender
+    TargetControlID="pnlNav"
+    HorizontalSide="HorizontalSide.Center"
+    VerticalSide="VerticalSide.Top"
+    VerticalOffset="0"
+    UseAnimation="false" />
+
+

Floating Notification (Top-Right)

+
@rendermode InteractiveServer
+
+<Panel ID="pnlNotification" style="width: 300px; padding: 15px; background-color: #FFC107; border-radius: 5px; box-shadow: 0 2px 5px rgba(0,0,0,0.2);">
+    <strong>Alert:</strong> You have 3 new messages.
+</Panel>
+
+<AlwaysVisibleControlExtender
+    TargetControlID="pnlNotification"
+    HorizontalSide="HorizontalSide.Right"
+    VerticalSide="VerticalSide.Top"
+    HorizontalOffset="20"
+    VerticalOffset="20"
+    UseAnimation="true"
+    ScrollEffectDuration="0.2" />
+
+

Sticky Side Panel (Left)

+
@rendermode InteractiveServer
+
+<Panel ID="pnlSidebar" style="width: 250px; padding: 20px; background-color: #f5f5f5; border-right: 1px solid #ccc;">
+    <h3>Quick Links</h3>
+    <ul>
+        <li><a href="#">Dashboard</a></li>
+        <li><a href="#">Settings</a></li>
+        <li><a href="#">Profile</a></li>
+    </ul>
+</Panel>
+
+<AlwaysVisibleControlExtender
+    TargetControlID="pnlSidebar"
+    HorizontalSide="HorizontalSide.Left"
+    VerticalSide="VerticalSide.Top"
+    VerticalOffset="0"
+    UseAnimation="true" />
+
+

HTML Output

+

The AlwaysVisibleControlExtender produces no HTML itself — it attaches JavaScript behavior to the target element, repositioning it as the user scrolls.

+

JavaScript Interop

+

The AlwaysVisibleControlExtender loads always-visible-control-extender.js as an ES module. JavaScript handles:

+
    +
  • Monitoring window scroll events
    • +
  • Calculating fixed position based on offsets and sides
    • +
  • Updating element position as user scrolls
    • +
  • Optional animation of position changes
    • +
  • Handling window resize events
    • +
  • Maintaining element visibility within viewport
    • +
+

Render Mode Requirements

+

The AlwaysVisibleControlExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The element displays at its normal position without scrolling.
    • +
  • JavaScript disabled: Same as SSR — Element does not stick to viewport.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:AlwaysVisibleControlExtender
++ <AlwaysVisibleControlExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use enum types for positioning + 

    - HorizontalSide="Right"
++ HorizontalSide="HorizontalSide.Right"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Panel ID="pnlHelp" runat="server" style="width: 250px; padding: 10px; background: #e3f2fd;">
+    <p>Help content</p>
+</asp:Panel>
+
+<ajaxToolkit:AlwaysVisibleControlExtender
+    ID="sticky1"
+    TargetControlID="pnlHelp"
+    HorizontalSide="Right"
+    VerticalSide="Bottom"
+    HorizontalOffset="20"
+    VerticalOffset="20"
+    runat="server" />
+
+

After (Blazor)

+
<Panel ID="pnlHelp" style="width: 250px; padding: 10px; background: #e3f2fd;">
+    <p>Help content</p>
+</Panel>
+
+<AlwaysVisibleControlExtender
+    TargetControlID="pnlHelp"
+    HorizontalSide="HorizontalSide.Right"
+    VerticalSide="VerticalSide.Bottom"
+    HorizontalOffset="20"
+    VerticalOffset="20" />
+
+

Best Practices

+
    +
  1. Use appropriate sizes — Keep sticky elements reasonably sized so they don't block content
    2. +
  2. Position wisely — Use corners or edges to avoid covering main content
    3. +
  3. Add offsets — Use HorizontalOffset and VerticalOffset to keep space from viewport edges
    4. +
  4. Consider mobile — Sticky elements on small screens can be intrusive; test responsiveness
    5. +
  5. Use animation — Enable UseAnimation for smooth repositioning as user scrolls
    6. +
  6. Include close button — Consider adding a close button to let users hide the sticky element
    7. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Element not staying visibleVerify TargetControlID matches the element's ID. Ensure @rendermode InteractiveServer is set.
Element covers contentAdjust HorizontalOffset, VerticalOffset, or position values. Choose a different corner.
Animation is jerkyReduce ScrollEffectDuration (try 0.05-0.15 seconds) or disable UseAnimation.
Element disappears on scrollCheck element's position CSS property. The extender uses position: fixed internally.
+

See Also

+
    +
  • Ajax Control Toolkit Overview — How extenders work and render mode requirements
    • +
  • Panel Component — The Panel control (documentation coming soon)
    • +
  • Original Ajax Control Toolkit: https://www.asp.net/ajax/ajaxcontroltoolkit
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/AutoCompleteExtender/index.html b/site/AjaxToolkit/AutoCompleteExtender/index.html new file mode 100644 index 000000000..38028bcba --- /dev/null +++ b/site/AjaxToolkit/AutoCompleteExtender/index.html @@ -0,0 +1,5326 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AutoCompleteExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

AutoCompleteExtender

+

The AutoCompleteExtender provides typeahead/autocomplete functionality for a target TextBox. As the user types, it fetches suggestions and renders a dropdown list with keyboard navigation support. Suggestions can be fetched via a service URL or a Blazor EventCallback.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/AutoCompleteExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the TextBox to enhance with autocomplete
    • +
  • ServicePath — URL of the web service providing completion data
    • +
  • ServiceMethod — Web service method name for completion data
    • +
  • MinimumPrefixLength — Minimum characters before suggestions are fetched
    • +
  • CompletionSetCount — Maximum number of suggestions to display
    • +
  • CompletionInterval — Milliseconds between keystrokes before fetching
    • +
  • CompletionListCssClass — CSS class for the dropdown container
    • +
  • CompletionListItemCssClass — CSS class for each dropdown item
    • +
  • CompletionListHighlightedItemCssClass — CSS class for the highlighted item
    • +
  • DelimiterCharacters — Characters that delimit separate entries in the TextBox
    • +
  • FirstRowSelected — Whether to auto-select the first suggestion
    • +
  • ShowOnlyCurrentWordInCompletionListItem — Show only the current word in suggestions
    • +
  • OnClientItemSelected — Script invoked when an item is selected
    • +
  • OnClientPopulating — Script invoked before the list is populated
    • +
  • OnClientPopulated — Script invoked after the list is populated
    • +
  • CompletionDataRequested — Blazor callback for server-side suggestion fetching
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Syntax

+
<asp:TextBox ID="txtSearch" runat="server" />
+
+<ajaxToolkit:AutoCompleteExtender
+    ID="ace1"
+    runat="server"
+    TargetControlID="txtSearch"
+    ServicePath="~/Services/SearchService.asmx"
+    ServiceMethod="GetSuggestions"
+    MinimumPrefixLength="2"
+    CompletionSetCount="10"
+    CompletionInterval="500"
+    CompletionListCssClass="autocomplete-list"
+    CompletionListItemCssClass="autocomplete-item"
+    CompletionListHighlightedItemCssClass="autocomplete-highlight"
+    FirstRowSelected="true" />
+
+

Blazor Migration

+
<TextBox ID="txtSearch" />
+
+<AutoCompleteExtender
+    TargetControlID="txtSearch"
+    ServicePath="/api/search"
+    ServiceMethod="GetSuggestions"
+    MinimumPrefixLength="2"
+    CompletionSetCount="10"
+    CompletionInterval="500"
+    CompletionListCssClass="autocomplete-list"
+    CompletionListItemCssClass="autocomplete-item"
+    CompletionListHighlightedItemCssClass="autocomplete-highlight"
+    FirstRowSelected="true" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Update the ServicePath to your new API endpoint. Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the TextBox to enhance with autocomplete
ServicePathstring""URL of the web service providing completion data
ServiceMethodstring""Web service method name to call for completion data
MinimumPrefixLengthint3Minimum characters typed before suggestions are fetched
CompletionSetCountint10Maximum number of suggestions to display
CompletionIntervalint1000Time in milliseconds between keystrokes before fetching suggestions
CompletionListCssClassstring""CSS class applied to the completion list dropdown container
CompletionListItemCssClassstring""CSS class applied to each item in the completion list
CompletionListHighlightedItemCssClassstring""CSS class applied to the highlighted item
DelimiterCharactersstring""Characters that delimit separate completion entries
FirstRowSelectedboolfalseWhether to auto-select the first item in the completion list
ShowOnlyCurrentWordInCompletionListItemboolfalseShow only the current word in each completion item
OnClientItemSelectedstring""Client-side script invoked when an item is selected
OnClientPopulatingstring""Client-side script invoked before the list is populated
OnClientPopulatedstring""Client-side script invoked after the list is populated
CompletionDataRequestedEventCallback<string>—Blazor callback for requesting completion data server-side
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Autocomplete with Service

+
@rendermode InteractiveServer
+
+<TextBox ID="txtCity" />
+
+<AutoCompleteExtender
+    TargetControlID="txtCity"
+    ServicePath="/api/cities"
+    ServiceMethod="Search"
+    MinimumPrefixLength="2"
+    CompletionSetCount="10" />
+
+

Autocomplete with Styled Dropdown

+
@rendermode InteractiveServer
+
+<TextBox ID="txtProduct" />
+
+<AutoCompleteExtender
+    TargetControlID="txtProduct"
+    ServicePath="/api/products"
+    ServiceMethod="Suggest"
+    MinimumPrefixLength="1"
+    CompletionSetCount="8"
+    CompletionInterval="300"
+    CompletionListCssClass="ac-dropdown"
+    CompletionListItemCssClass="ac-item"
+    CompletionListHighlightedItemCssClass="ac-item-highlight"
+    FirstRowSelected="true" />
+
+<style>
+    .ac-dropdown {
+        border: 1px solid #ccc; background: white;
+        max-height: 200px; overflow-y: auto; box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+    }
+    .ac-item { padding: 8px 12px; cursor: pointer; }
+    .ac-item-highlight { background: #007bff; color: white; }
+</style>
+
+

Multi-Value Autocomplete with Delimiters

+
@rendermode InteractiveServer
+
+<TextBox ID="txtTags" />
+
+<AutoCompleteExtender
+    TargetControlID="txtTags"
+    ServicePath="/api/tags"
+    ServiceMethod="Search"
+    MinimumPrefixLength="1"
+    DelimiterCharacters=",;"
+    ShowOnlyCurrentWordInCompletionListItem="true" />
+
+

Autocomplete with JavaScript Callbacks

+
@rendermode InteractiveServer
+
+<TextBox ID="txtEmployee" />
+
+<AutoCompleteExtender
+    TargetControlID="txtEmployee"
+    ServicePath="/api/employees"
+    ServiceMethod="Find"
+    MinimumPrefixLength="2"
+    OnClientItemSelected="onEmployeeSelected"
+    OnClientPopulating="onSearchStart"
+    OnClientPopulated="onSearchEnd" />
+
+<script>
+    function onEmployeeSelected(sender, args) {
+        console.log('Selected:', args);
+    }
+    function onSearchStart() {
+        console.log('Searching...');
+    }
+    function onSearchEnd() {
+        console.log('Search complete');
+    }
+</script>
+
+

HTML Output

+

The AutoCompleteExtender produces no HTML itself — it attaches JavaScript behavior to the target TextBox. When suggestions are fetched, the JavaScript module creates and manages a dropdown list in the DOM.

+

JavaScript Interop

+

The AutoCompleteExtender loads autocomplete-extender.js as an ES module. JavaScript handles:

+
    +
  • Monitoring keystrokes and debouncing requests
    • +
  • Fetching suggestions from the configured service endpoint
    • +
  • Rendering and positioning the dropdown list
    • +
  • Keyboard navigation (Up/Down arrows, Enter to select, Escape to close)
    • +
  • Highlighting the selected item
    • +
  • Delimiter-aware text insertion
    • +
+

Render Mode Requirements

+

The AutoCompleteExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The TextBox works as a plain text input.
    • +
  • JavaScript disabled: Same as SSR — TextBox functions without autocomplete.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:AutoCompleteExtender
++ <AutoCompleteExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Update ServicePath — Change from .asmx paths to your new API endpoints + 

    - ServicePath="~/Services/SearchService.asmx"
++ ServicePath="/api/search"
+

    +
    4. +
  4. +

    Consider using CompletionDataRequested — For Blazor-native data fetching instead of web services

    +
    5. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtSearch" runat="server" />
+
+<ajaxToolkit:AutoCompleteExtender
+    ID="ace1"
+    TargetControlID="txtSearch"
+    ServicePath="~/SearchService.asmx"
+    ServiceMethod="GetSuggestions"
+    MinimumPrefixLength="2"
+    CompletionSetCount="10"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtSearch" />
+
+<AutoCompleteExtender
+    TargetControlID="txtSearch"
+    ServicePath="/api/search"
+    ServiceMethod="GetSuggestions"
+    MinimumPrefixLength="2"
+    CompletionSetCount="10" />
+
+

Best Practices

+
    +
  1. Set appropriate MinimumPrefixLength — Too low (1) causes excessive requests; too high (5) feels unresponsive
    2. +
  2. Tune CompletionInterval — 300–500ms is a good balance between responsiveness and server load
    3. +
  3. Limit CompletionSetCount — 8–12 items keeps the dropdown manageable
    4. +
  4. Style the dropdown — Use CSS classes to match your application's design
    5. +
  5. Handle empty results gracefully — Consider showing a "No results" message
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
No suggestions appearingVerify ServicePath and ServiceMethod are correct and returning data. Check MinimumPrefixLength isn't too high. Ensure @rendermode InteractiveServer is set.
Suggestions appear slowlyReduce CompletionInterval (e.g., 300ms). Check server response times.
Wrong item highlightedVerify CompletionListHighlightedItemCssClass is set and has visible styling.
Delimiter mode not workingEnsure DelimiterCharacters contains the correct separator characters.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/BalloonPopupExtender/index.html b/site/AjaxToolkit/BalloonPopupExtender/index.html new file mode 100644 index 000000000..d9a71823b --- /dev/null +++ b/site/AjaxToolkit/BalloonPopupExtender/index.html @@ -0,0 +1,5455 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BalloonPopupExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

BalloonPopupExtender

+

The BalloonPopupExtender displays a balloon or tooltip-style popup with a pointer arrow when the user hovers over, focuses on, or clicks a target element. The popup displays content from a specified container element and can be customized with different styles (Rectangle, Cloud, Custom), sizes, shadows, and scrollbar settings.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/BalloonPopupExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the element that triggers the balloon
    • +
  • BalloonPopupControlID — ID of the element containing balloon content
    • +
  • Position — Where the balloon appears (TopLeft, TopRight, BottomLeft, BottomRight, Auto)
    • +
  • BalloonStyle — Visual style (Rectangle, Cloud, Custom)
    • +
  • BalloonSize — Size preset (Small, Medium, Large)
    • +
  • UseShadow — Whether to display a drop shadow
    • +
  • ScrollBars — Scrollbar behavior (Auto, None, Horizontal, Vertical, Both)
    • +
  • DisplayOnMouseOver — Show balloon on hover
    • +
  • DisplayOnFocus — Show balloon on focus
    • +
  • DisplayOnClick — Show balloon on click
    • +
  • OffsetX — Horizontal offset in pixels
    • +
  • OffsetY — Vertical offset in pixels
    • +
  • CustomCssUrl — URL to custom CSS (for Custom style)
    • +
+

Position Enum

+

Controls balloon position:

+
enum BalloonPosition
+{
+    TopLeft = 0,
+    TopRight = 1,
+    BottomLeft = 2,
+    BottomRight = 3,
+    Auto = 4  // Automatically position to stay in viewport
+}
+
+

BalloonStyle Enum

+

Controls visual appearance:

+
enum BalloonStyle
+{
+    Rectangle = 0,  // Simple rectangle with border
+    Cloud = 1,      // Cloud-like rounded shape
+    Custom = 2      // Custom styling via CSS
+}
+
+

BalloonSize Enum

+

Controls balloon dimensions:

+
enum BalloonSize
+{
+    Small = 0,    // Compact size
+    Medium = 1,   // Standard size
+    Large = 2     // Spacious size
+}
+
+

Web Forms Syntax

+
<asp:TextBox ID="txtEmail" runat="server" />
+
+<div id="balloonContent" style="display: none;">
+    <p>Enter a valid email address (e.g., user@example.com)</p>
+</div>
+
+<ajaxToolkit:BalloonPopupExtender
+    ID="balloon1"
+    runat="server"
+    TargetControlID="txtEmail"
+    BalloonPopupControlID="balloonContent"
+    Position="BottomRight"
+    BalloonStyle="Cloud"
+    BalloonSize="Medium"
+    UseShadow="true"
+    DisplayOnFocus="true" />
+
+

Blazor Migration

+
<TextBox ID="txtEmail" />
+
+<div id="balloonContent" style="display: none;">
+    <p>Enter a valid email address (e.g., user@example.com)</p>
+</div>
+
+<BalloonPopupExtender
+    TargetControlID="txtEmail"
+    BalloonPopupControlID="balloonContent"
+    Position="BalloonPosition.BottomRight"
+    BalloonStyle="BalloonStyle.Cloud"
+    BalloonSize="BalloonSize.Medium"
+    UseShadow="true"
+    DisplayOnFocus="true" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Use enum type names!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the element that triggers the balloon popup
BalloonPopupControlIDstring(required)ID of the element containing the balloon content
PositionBalloonPositionAutoPosition of the balloon relative to target (TopLeft, TopRight, BottomLeft, BottomRight, Auto)
BalloonStyleBalloonStyleRectangleVisual style of the balloon (Rectangle, Cloud, Custom)
BalloonSizeBalloonSizeMediumSize preset (Small, Medium, Large)
UseShadowbooltrueWhether to display a drop shadow on the balloon
ScrollBarsScrollBarsAutoScrollbar behavior when content exceeds balloon size
DisplayOnMouseOverbooltrueShow balloon when mouse hovers over target
DisplayOnFocusboolfalseShow balloon when target receives focus
DisplayOnClickboolfalseShow balloon when target is clicked
OffsetXint0Horizontal offset in pixels from calculated position
OffsetYint0Vertical offset in pixels from calculated position
CustomCssUrlstring""URL to custom CSS file (only used with BalloonStyle.Custom)
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Help Tooltip on Input

+
@rendermode InteractiveServer
+
+<form>
+    <label>Email Address:</label>
+    <TextBox ID="txtEmail" type="email" style="width: 200px;" />
+
+    <div id="emailHelp" style="display: none; padding: 10px;">
+        <p><strong>Email Format:</strong></p>
+        <p>user@domain.com</p>
+    </div>
+
+    <BalloonPopupExtender
+        TargetControlID="txtEmail"
+        BalloonPopupControlID="emailHelp"
+        Position="BalloonPosition.BottomRight"
+        BalloonStyle="BalloonStyle.Cloud"
+        BalloonSize="BalloonSize.Small"
+        DisplayOnFocus="true"
+        DisplayOnMouseOver="true" />
+</form>
+
+

Cloud-Style Information Popup

+
@rendermode InteractiveServer
+
+<button id="btnInfo" style="background: #2196F3; color: white; padding: 8px 16px; border-radius: 4px; cursor: pointer;">
+    ? Info
+</button>
+
+<div id="infoContent" style="display: none; padding: 15px;">
+    <h4>How to Use:</h4>
+    <ol>
+        <li>Fill in all required fields</li>
+        <li>Click the Submit button</li>
+        <li>Confirmation will be sent via email</li>
+    </ol>
+</div>
+
+<BalloonPopupExtender
+    TargetControlID="btnInfo"
+    BalloonPopupControlID="infoContent"
+    Position="BalloonPosition.Auto"
+    BalloonStyle="BalloonStyle.Cloud"
+    BalloonSize="BalloonSize.Large"
+    DisplayOnClick="true"
+    UseShadow="true" />
+
+

Rectangle-Style Note

+
@rendermode InteractiveServer
+
+<label>Password:</label>
+<TextBox ID="txtPassword" type="password" style="width: 200px;" />
+
+<div id="passwordNote" style="display: none; padding: 10px; background: #fffacd; border-left: 3px solid #ffc107;">
+    <strong>Password Requirements:</strong>
+    <ul style="margin: 5px 0; padding-left: 20px;">
+        <li>Minimum 8 characters</li>
+        <li>At least one number</li>
+        <li>At least one symbol</li>
+    </ul>
+</div>
+
+<BalloonPopupExtender
+    TargetControlID="txtPassword"
+    BalloonPopupControlID="passwordNote"
+    Position="BalloonPosition.BottomRight"
+    BalloonStyle="BalloonStyle.Rectangle"
+    BalloonSize="BalloonSize.Medium"
+    DisplayOnFocus="true"
+    OffsetX="10"
+    OffsetY="5" />
+
+

Multi-Purpose Tooltips

+
@rendermode InteractiveServer
+
+<table>
+    <tr>
+        <td>
+            <label>First Name:</label>
+            <input id="firstNameInput" type="text" />
+        </td>
+        <td>
+            <span id="firstNameHelp" style="cursor: help; color: #2196F3; font-weight: bold;">?</span>
+            <div id="firstNamePopup" style="display: none; padding: 8px;">
+                Your legal first name
+            </div>
+
+            <BalloonPopupExtender
+                TargetControlID="firstNameHelp"
+                BalloonPopupControlID="firstNamePopup"
+                Position="BalloonPosition.TopRight"
+                BalloonStyle="BalloonStyle.Cloud"
+                BalloonSize="BalloonSize.Small"
+                DisplayOnMouseOver="true" />
+        </td>
+    </tr>
+    <tr>
+        <td>
+            <label>Last Name:</label>
+            <input id="lastNameInput" type="text" />
+        </td>
+        <td>
+            <span id="lastNameHelp" style="cursor: help; color: #2196F3; font-weight: bold;">?</span>
+            <div id="lastNamePopup" style="display: none; padding: 8px;">
+                Your legal last name
+            </div>
+
+            <BalloonPopupExtender
+                TargetControlID="lastNameHelp"
+                BalloonPopupControlID="lastNamePopup"
+                Position="BalloonPosition.TopRight"
+                BalloonStyle="BalloonStyle.Cloud"
+                BalloonSize="BalloonSize.Small"
+                DisplayOnMouseOver="true" />
+        </td>
+    </tr>
+</table>
+
+

HTML Output

+

The BalloonPopupExtender creates or repositions the balloon popup element based on the target's position and configured settings.

+

JavaScript Interop

+

The BalloonPopupExtender loads balloon-popup-extender.js as an ES module. JavaScript handles:

+
    +
  • Detecting trigger events (hover, focus, click) on target
    • +
  • Positioning balloon relative to target and viewport
    • +
  • Displaying/hiding the balloon popup
    • +
  • Applying balloon style and size classes
    • +
  • Managing shadow display
    • +
  • Scrollbar handling for overflow content
    • +
  • Repositioning on window scroll/resize
    • +
  • Closing balloon on outside click
    • +
  • Offset calculations
    • +
+

Render Mode Requirements

+

The BalloonPopupExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. Content remains hidden.
    • +
  • JavaScript disabled: Same as SSR — Balloon doesn't appear.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:BalloonPopupExtender
++ <BalloonPopupExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use enum types for position, style, and size + 

    - Position="BottomRight"
++ Position="BalloonPosition.BottomRight"
+- BalloonStyle="Cloud"
++ BalloonStyle="BalloonStyle.Cloud"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtField" runat="server" />
+
+<div id="popupContent" style="display: none;">
+    <p>Help text</p>
+</div>
+
+<ajaxToolkit:BalloonPopupExtender
+    ID="balloon1"
+    TargetControlID="txtField"
+    BalloonPopupControlID="popupContent"
+    Position="BottomRight"
+    BalloonStyle="Cloud"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtField" />
+
+<div id="popupContent" style="display: none;">
+    <p>Help text</p>
+</div>
+
+<BalloonPopupExtender
+    TargetControlID="txtField"
+    BalloonPopupControlID="popupContent"
+    Position="BalloonPosition.BottomRight"
+    BalloonStyle="BalloonStyle.Cloud" />
+
+

Best Practices

+
    +
  1. Use Auto position when possible — Automatically keeps balloon in viewport
    2. +
  2. Hide content initially — Keep balloon content hidden with display: none until needed
    3. +
  3. Keep content brief — Balloons work best for short help text or quick info
    4. +
  4. Test viewport positioning — Ensure balloons don't get cut off on small screens
    5. +
  5. Use Cloud style for friendly UI — Cloud style works well for help and tips
    6. +
  6. Consider accessibility — Provide alternative ways to access information for users who don't hover
    7. +
  7. Limit trigger events — Choose specific trigger events (hover, focus, or click) rather than all
    8. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Balloon not appearingVerify both TargetControlID and BalloonPopupControlID match actual element IDs. Ensure content div has display: none. Check @rendermode InteractiveServer.
Balloon positioned off-screenUse Position="BalloonPosition.Auto" for automatic viewport-aware positioning, or adjust OffsetX/OffsetY.
Content not visibleEnsure the content div (BalloonPopupControlID) is not accidentally hidden or has no height.
Multiple balloons interferingEach target should have its own unique balloon content div with unique ID.
Trigger events not workingVerify DisplayOnMouseOver, DisplayOnFocus, or DisplayOnClick are enabled as desired.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/CalendarExtender/index.html b/site/AjaxToolkit/CalendarExtender/index.html new file mode 100644 index 000000000..146f22419 --- /dev/null +++ b/site/AjaxToolkit/CalendarExtender/index.html @@ -0,0 +1,5310 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CalendarExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

CalendarExtender

+

The CalendarExtender attaches a popup calendar date picker to a target TextBox. When the user focuses or clicks the TextBox, a calendar dropdown appears allowing date selection. It supports configurable date formats, navigation views, and date range constraints.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/CalendarExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the TextBox to attach the calendar to
    • +
  • Format — Date format string used to display and parse dates
    • +
  • PopupPosition — Position of the popup calendar relative to the target
    • +
  • DefaultView — The default view when the calendar opens (Days, Months, Years)
    • +
  • StartDate — The earliest selectable date
    • +
  • EndDate — The latest selectable date
    • +
  • SelectedDate — The currently selected date
    • +
  • TodaysDate — The date highlighted as today
    • +
  • CssClass — CSS class applied to the calendar popup container
    • +
  • OnClientDateSelectionChanged — Client-side script invoked when a date is selected
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

CalendarPosition Enum

+

Controls the position of the popup calendar:

+
enum CalendarPosition
+{
+    BottomLeft = 0,   // Below target, left-aligned (default)
+    BottomRight = 1,  // Below target, right-aligned
+    TopLeft = 2,      // Above target, left-aligned
+    TopRight = 3,     // Above target, right-aligned
+    Right = 4,        // To the right of target
+    Left = 5          // To the left of target
+}
+
+

CalendarDefaultView Enum

+

Controls the initial view when the calendar opens:

+
enum CalendarDefaultView
+{
+    Days = 0,    // Day grid (default)
+    Months = 1,  // Month picker
+    Years = 2    // Year picker
+}
+
+

Web Forms Syntax

+
<asp:TextBox ID="txtDate" runat="server" />
+
+<ajaxToolkit:CalendarExtender
+    ID="cal1"
+    runat="server"
+    TargetControlID="txtDate"
+    Format="MM/dd/yyyy"
+    PopupPosition="BottomLeft"
+    DefaultView="Days"
+    StartDate="01/01/2020"
+    EndDate="12/31/2030"
+    OnClientDateSelectionChanged="onDateSelected" />
+
+

Blazor Migration

+
<TextBox ID="txtDate" />
+
+<CalendarExtender
+    TargetControlID="txtDate"
+    Format="MM/dd/yyyy"
+    PopupPosition="CalendarPosition.BottomLeft"
+    DefaultView="CalendarDefaultView.Days"
+    StartDate="@(new DateTime(2020, 1, 1))"
+    EndDate="@(new DateTime(2030, 12, 31))"
+    OnClientDateSelectionChanged="onDateSelected" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Date constraints use DateTime? instead of strings. Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the TextBox to attach the calendar to
Formatstring"d"Date format string used to display and parse dates (e.g., "MM/dd/yyyy")
PopupPositionCalendarPositionBottomLeftPosition of the popup calendar relative to the target
DefaultViewCalendarDefaultViewDaysThe default view when the calendar opens
StartDateDateTime?nullThe earliest selectable date; dates before this are disabled
EndDateDateTime?nullThe latest selectable date; dates after this are disabled
SelectedDateDateTime?nullThe currently selected date
TodaysDateDateTime?nullThe date highlighted as today (defaults to current date if not set)
CssClassstring""CSS class applied to the calendar popup container
OnClientDateSelectionChangedstring""Client-side script invoked when a date is selected
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Date Picker

+
@rendermode InteractiveServer
+
+<TextBox ID="txtBirthDate" />
+
+<CalendarExtender
+    TargetControlID="txtBirthDate"
+    Format="MM/dd/yyyy" />
+
+

Date Picker with Range Constraints

+
@rendermode InteractiveServer
+
+<TextBox ID="txtBooking" />
+
+<CalendarExtender
+    TargetControlID="txtBooking"
+    Format="yyyy-MM-dd"
+    StartDate="@DateTime.Today"
+    EndDate="@DateTime.Today.AddYears(1)"
+    PopupPosition="CalendarPosition.BottomRight" />
+
+

Date Picker with Year View

+
@rendermode InteractiveServer
+
+<TextBox ID="txtYear" />
+
+<CalendarExtender
+    TargetControlID="txtYear"
+    Format="yyyy"
+    DefaultView="CalendarDefaultView.Years" />
+
+

Date Picker with JavaScript Callback

+
@rendermode InteractiveServer
+
+<TextBox ID="txtEvent" />
+
+<CalendarExtender
+    TargetControlID="txtEvent"
+    Format="MM/dd/yyyy"
+    OnClientDateSelectionChanged="onDatePicked" />
+
+<script>
+    function onDatePicked() {
+        var dateField = document.getElementById('txtEvent');
+        console.log('Date selected:', dateField.value);
+    }
+</script>
+
+

HTML Output

+

The CalendarExtender produces no HTML itself — it attaches JavaScript behavior to the target TextBox. When activated, the JavaScript module creates and manages the calendar popup in the DOM.

+

JavaScript Interop

+

The CalendarExtender loads calendar-extender.js as an ES module. JavaScript handles:

+
    +
  • Rendering the calendar popup with day/month/year views
    • +
  • Date navigation (previous/next month, year)
    • +
  • Date selection and formatting
    • +
  • Date range enforcement (disabling out-of-range dates)
    • +
  • Popup positioning relative to the target control
    • +
  • Closing the calendar on outside click or Escape key
    • +
+

Render Mode Requirements

+

The CalendarExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The TextBox works as a plain text input.
    • +
  • JavaScript disabled: Same as SSR — TextBox functions without a calendar popup.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:CalendarExtender
++ <CalendarExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Date parameters use DateTime? instead of strings + 

    - StartDate="01/01/2020"
++ StartDate="@(new DateTime(2020, 1, 1))"
+

    +
    4. +
  4. +

    Enum values use full type names + 

    - PopupPosition="BottomLeft"
++ PopupPosition="CalendarPosition.BottomLeft"
+

    +
    5. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtDate" runat="server" />
+
+<ajaxToolkit:CalendarExtender
+    ID="cal1"
+    TargetControlID="txtDate"
+    Format="MM/dd/yyyy"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtDate" />
+
+<CalendarExtender
+    TargetControlID="txtDate"
+    Format="MM/dd/yyyy" />
+
+

Best Practices

+
    +
  1. Specify a clear format — Use Format to match your application's date convention
    2. +
  2. Set date ranges — Use StartDate/EndDate to prevent invalid date selection
    3. +
  3. Position wisely — Choose PopupPosition to avoid clipping by page edges
    4. +
  4. Provide fallback — The TextBox still accepts typed input when the calendar isn't available
    5. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Calendar not appearingVerify TargetControlID matches the TextBox's ID. Ensure @rendermode InteractiveServer is set.
Wrong date formatCheck the Format string matches your expected output (e.g., "MM/dd/yyyy").
Dates outside range selectableVerify StartDate and EndDate are set correctly as DateTime? values.
Calendar positioned off-screenTry a different PopupPosition value or ensure the target has enough viewport space.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/CollapsiblePanelExtender/index.html b/site/AjaxToolkit/CollapsiblePanelExtender/index.html new file mode 100644 index 000000000..85cc84af7 --- /dev/null +++ b/site/AjaxToolkit/CollapsiblePanelExtender/index.html @@ -0,0 +1,5807 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CollapsiblePanelExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

CollapsiblePanelExtender

+

The CollapsiblePanelExtender adds collapse/expand functionality to a target panel with smooth CSS transitions. It supports separate trigger controls for collapse and expand, dynamic label text updates, automatic collapse/expand on mouse events, and configurable animation directions.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/CollapsiblePanelExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the panel to make collapsible
    • +
  • CollapseControlID — ID of the element that triggers collapse
    • +
  • ExpandControlID — ID of the element that triggers expand
    • +
  • Collapsed — Whether the panel starts in collapsed state
    • +
  • CollapsedSize — Height/width in pixels when collapsed (0 = fully hidden)
    • +
  • ExpandedSize — Height/width in pixels when expanded (0 = auto)
    • +
  • CollapsedText — Text to display when collapsed
    • +
  • ExpandedText — Text to display when expanded
    • +
  • TextLabelID — ID of the element whose text changes with state
    • +
  • ExpandDirection — Direction of collapse/expand animation (Vertical or Horizontal)
    • +
  • AutoCollapse — Automatically collapse when mouse leaves
    • +
  • AutoExpand — Automatically expand when mouse enters
    • +
  • ScrollContents — Enable scrollbars when panel content overflows
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

ExpandDirection Enum

+

Controls the direction of the collapse/expand animation:

+
enum ExpandDirection
+{
+    Vertical = 0,    // Collapse top-to-bottom (default)
+    Horizontal = 1   // Collapse left-to-right
+}
+
+

Web Forms Syntax

+
<asp:Button ID="btnToggle" Text="Click to expand" runat="server" />
+
+<asp:Panel ID="pnlContent" style="display: none;">
+    <p>This content can be collapsed and expanded.</p>
+</asp:Panel>
+
+<ajaxToolkit:CollapsiblePanelExtender 
+    ID="cpe"
+    runat="server"
+    TargetControlID="pnlContent"
+    CollapseControlID="btnToggle"
+    ExpandControlID="btnToggle"
+    CollapsedText="▶ Show Details"
+    ExpandedText="▼ Hide Details"
+    TextLabelID="btnToggle"
+    Collapsed="true" />
+
+

Blazor Migration

+
<Button ID="btnToggle" Text="Click to expand" />
+
+<div ID="pnlContent" style="display: none; overflow: hidden;">
+    <p>This content can be collapsed and expanded.</p>
+</div>
+
+<CollapsiblePanelExtender 
+    TargetControlID="pnlContent"
+    CollapseControlID="btnToggle"
+    ExpandControlID="btnToggle"
+    CollapsedText="▶ Show Details"
+    ExpandedText="▼ Hide Details"
+    TextLabelID="btnToggle"
+    Collapsed="true" />
+
+

Migration is simple: Just remove the ajaxToolkit: prefix and remove the runat="server" and ID attributes. Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the panel/element to make collapsible
CollapseControlIDstring""ID of the element that triggers collapse
ExpandControlIDstring""ID of the element that triggers expand (can equal CollapseControlID for toggle)
CollapsedboolfalseWhether the panel starts in collapsed state
CollapsedSizeint0Height/width in pixels when collapsed (0 = fully hidden)
ExpandedSizeint0Height/width in pixels when expanded (0 = auto-size based on content)
CollapsedTextstring""Text to display in TextLabelID element when collapsed
ExpandedTextstring""Text to display in TextLabelID element when expanded
TextLabelIDstring""ID of the element whose text content changes with state
ExpandDirectionExpandDirectionVerticalDirection of animation: Vertical (top-to-bottom) or Horizontal (left-to-right)
AutoCollapseboolfalseAutomatically collapse when mouse leaves the panel
AutoExpandboolfalseAutomatically expand when mouse enters the panel
ScrollContentsboolfalseEnable scrollbars within the panel when content overflows
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Simple Collapse/Expand

+
@rendermode InteractiveServer
+
+<button ID="btnToggle" style="padding: 10px 20px; cursor: pointer; background: #007bff; color: white; border: none; border-radius: 4px; font-weight: bold;">
+    Show Details
+</button>
+
+<div ID="detailsPanel" style="display: none; overflow: hidden; margin-top: 15px; padding: 20px; background: #f8f9fa; border: 1px solid #dee2e6; border-radius: 4px;">
+    <h4>Details</h4>
+    <p>This content expands and collapses smoothly with CSS transitions.</p>
+    <ul>
+        <li>Item 1</li>
+        <li>Item 2</li>
+        <li>Item 3</li>
+    </ul>
+</div>
+
+<CollapsiblePanelExtender 
+    TargetControlID="detailsPanel"
+    CollapseControlID="btnToggle"
+    ExpandControlID="btnToggle"
+    CollapsedText="▶ Show Details"
+    ExpandedText="▼ Hide Details"
+    TextLabelID="btnToggle"
+    Collapsed="true" />
+
+

Separate Expand/Collapse Buttons

+
@rendermode InteractiveServer
+
+<div style="display: flex; gap: 10px; margin-bottom: 15px;">
+    <button ID="btnExpand" style="padding: 8px 16px; cursor: pointer; background: #28a745; color: white; border: none; border-radius: 4px;">
+        ▲ Expand All
+    </button>
+    <button ID="btnCollapse" style="padding: 8px 16px; cursor: pointer; background: #dc3545; color: white; border: none; border-radius: 4px;">
+        ▼ Collapse All
+    </button>
+</div>
+
+<div ID="settingsPanel" style="display: none; overflow: hidden; padding: 20px; background: white; border: 1px solid #dee2e6; border-radius: 4px;">
+    <h4>Advanced Settings</h4>
+    <label style="display: block; margin: 10px 0;">
+        <input type="checkbox" @bind-checked="@setting1" />
+        Enable feature 1
+    </label>
+    <label style="display: block; margin: 10px 0;">
+        <input type="checkbox" @bind-checked="@setting2" />
+        Enable feature 2
+    </label>
+    <label style="display: block; margin: 10px 0;">
+        <input type="checkbox" @bind-checked="@setting3" />
+        Enable feature 3
+    </label>
+</div>
+
+<CollapsiblePanelExtender 
+    TargetControlID="settingsPanel"
+    ExpandControlID="btnExpand"
+    CollapseControlID="btnCollapse"
+    Collapsed="true" />
+
+@code {
+    private bool setting1 = false;
+    private bool setting2 = true;
+    private bool setting3 = false;
+}
+
+

Auto-Collapse/Expand on Hover

+
@rendermode InteractiveServer
+
+<div style="max-width: 300px;">
+    <div ID="hoverPanel" style="display: none; overflow: hidden; padding: 20px; background: #fff3cd; border: 1px solid #ffc107; border-radius: 4px;">
+        <p>Hover over this area to expand. Move your mouse away to collapse.</p>
+        <p>This is useful for tooltips or quick previews.</p>
+    </div>
+</div>
+
+<CollapsiblePanelExtender 
+    TargetControlID="hoverPanel"
+    ExpandControlID="hoverPanel"
+    CollapseControlID="hoverPanel"
+    AutoExpand="true"
+    AutoCollapse="true"
+    Collapsed="true" />
+
+<style>
+    #hoverPanel {
+        transition: all 0.3s ease;
+    }
+</style>
+
+

Horizontal Collapse (Sidebar-Style)

+
@rendermode InteractiveServer
+
+<div style="display: flex; gap: 20px;">
+    <button ID="btnToggleSidebar" style="padding: 8px 16px; cursor: pointer; background: #6c757d; color: white; border: none; border-radius: 4px;">
+        ☰ Menu
+    </button>
+
+    <div ID="sidebarPanel" style="display: none; overflow: hidden; min-width: 200px; background: #f8f9fa; padding: 20px; border-right: 1px solid #dee2e6;">
+        <ul style="list-style: none; padding: 0;">
+            <li><a href="#" style="display: block; padding: 10px 0; text-decoration: none; color: #007bff;">Dashboard</a></li>
+            <li><a href="#" style="display: block; padding: 10px 0; text-decoration: none; color: #007bff;">Users</a></li>
+            <li><a href="#" style="display: block; padding: 10px 0; text-decoration: none; color: #007bff;">Reports</a></li>
+            <li><a href="#" style="display: block; padding: 10px 0; text-decoration: none; color: #007bff;">Settings</a></li>
+        </ul>
+    </div>
+
+    <div style="flex: 1;">
+        <h2>Main Content</h2>
+        <p>Content area that grows when sidebar is hidden.</p>
+    </div>
+</div>
+
+<CollapsiblePanelExtender 
+    TargetControlID="sidebarPanel"
+    CollapseControlID="btnToggleSidebar"
+    ExpandControlID="btnToggleSidebar"
+    ExpandDirection="ExpandDirection.Horizontal"
+    Collapsed="false" />
+
+

FAQ Accordion Pattern

+
@rendermode InteractiveServer
+
+<div style="max-width: 600px;">
+    @foreach (var item in faqItems)
+    {
+        <div style="margin-bottom: 10px; border: 1px solid #dee2e6; border-radius: 4px;">
+            <button ID="@($"faqBtn{item.Id}")" 
+                    style="width: 100%; padding: 15px; text-align: left; background: #f8f9fa; border: none; cursor: pointer; font-weight: bold; display: flex; justify-content: space-between; align-items: center;">
+                @item.Question
+                <span style="font-size: 12px;">►</span>
+            </button>
+
+            <div ID="@($"faqContent{item.Id}")" style="display: none; overflow: hidden; padding: 20px; background: white; border-top: 1px solid #dee2e6;">
+                <p>@item.Answer</p>
+            </div>
+        </div>
+
+        <CollapsiblePanelExtender 
+            TargetControlID="@($"faqContent{item.Id}")"
+            CollapseControlID="@($"faqBtn{item.Id}")"
+            ExpandControlID="@($"faqBtn{item.Id}")"
+            CollapsedText="▶"
+            ExpandedText="▼"
+            TextLabelID="@($"faqBtn{item.Id}")"
+            Collapsed="true" />
+    }
+</div>
+
+@code {
+    private class FaqItem
+    {
+        public int Id { get; set; }
+        public string Question { get; set; } = "";
+        public string Answer { get; set; } = "";
+    }
+
+    private List<FaqItem> faqItems = new()
+    {
+        new FaqItem { Id = 1, Question = "What is Blazor?", Answer = "Blazor is a framework for building interactive web applications with C# instead of JavaScript." },
+        new FaqItem { Id = 2, Question = "How do I migrate from Web Forms?", Answer = "Use BlazorWebFormsComponents (BWFC) to emulate familiar Web Forms controls with minimal markup changes." },
+        new FaqItem { Id = 3, Question = "Is BWFC production-ready?", Answer = "Yes, BWFC is production-ready. It has been tested extensively and is used in production applications." }
+    };
+}
+
+

Panel with Scrollable Content

+
@rendermode InteractiveServer
+
+<button ID="btnToggleLog" style="padding: 10px 20px; cursor: pointer; background: #007bff; color: white; border: none; border-radius: 4px;">
+    Show Log
+</button>
+
+<div ID="logPanel" style="display: none; overflow: hidden; margin-top: 15px; max-height: 300px; border: 1px solid #dee2e6; border-radius: 4px; background: #f8f9fa;">
+    <div style="padding: 15px; font-family: monospace; font-size: 12px;">
+        <div>[2026-03-15 10:25:00] Application started</div>
+        <div>[2026-03-15 10:25:01] Database connected</div>
+        <div>[2026-03-15 10:25:02] Loading configuration</div>
+        <div>[2026-03-15 10:25:03] Initializing services</div>
+        <div>[2026-03-15 10:25:04] Ready</div>
+        <div>[2026-03-15 10:26:01] User login attempt</div>
+        <div>[2026-03-15 10:26:02] Authentication successful</div>
+        <div>[2026-03-15 10:26:15] Page load: /dashboard</div>
+    </div>
+</div>
+
+<CollapsiblePanelExtender 
+    TargetControlID="logPanel"
+    CollapseControlID="btnToggleLog"
+    ExpandControlID="btnToggleLog"
+    CollapsedText="▶ Show Log"
+    ExpandedText="▼ Hide Log"
+    TextLabelID="btnToggleLog"
+    ScrollContents="true"
+    Collapsed="true" />
+
+

Starting Expanded with Partial Visibility

+
@rendermode InteractiveServer
+
+<button ID="btnTogglePreview" style="padding: 10px 20px; cursor: pointer; background: #007bff; color: white; border: none; border-radius: 4px;">
+    ▼ Hide Preview
+</button>
+
+<div ID="previewPanel" style="overflow: hidden; margin-top: 15px; padding: 20px; background: #e7f3ff; border: 1px solid #0066cc; border-radius: 4px;">
+    <p>Preview shows the first few lines of content. Click the button to show all details.</p>
+    <p>Line 2 of preview content</p>
+    <p>Line 3 of preview content</p>
+    <p>Line 4 of preview content</p>
+    <p>Line 5 of preview content</p>
+</div>
+
+<CollapsiblePanelExtender 
+    TargetControlID="previewPanel"
+    CollapseControlID="btnTogglePreview"
+    ExpandControlID="btnTogglePreview"
+    CollapsedSize="120"
+    CollapsedText="▶ Show Full Content"
+    ExpandedText="▼ Hide Preview"
+    TextLabelID="btnTogglePreview"
+    Collapsed="false" />
+
+

HTML Output

+

The CollapsiblePanelExtender produces no HTML itself — it only attaches JavaScript behavior to the target panel.

+

Before (initial state, collapsed): +

<button id="btnToggle" style="...">▶ Show Details</button>
+
+<div id="detailsPanel" style="display: none; overflow: hidden; ...">
+    Content here
+</div>
+

+

After expand (via JavaScript): +

<button id="btnToggle" style="...">▼ Hide Details</button>
+
+<div id="detailsPanel" style="display: block; overflow: hidden; height: 200px; transition: height 0.3s ease; ...">
+    Content here
+</div>
+

+

Collapsible Panel Behavior

+

Animation

+
    +
  • Collapse/expand uses CSS height transitions for smooth animation
    • +
  • Animation duration is typically 0.3s (controlled by CSS)
    • +
  • During animation, overflow: hidden prevents content from showing outside bounds
    • +
+

Initial State

+
    +
  • If Collapsed="true", panel starts hidden (or at CollapsedSize)
    • +
  • If Collapsed="false", panel starts visible at full height
    • +
  • TextLabelID text updates based on initial state
    • +
+

Text Updates

+
    +
  • When panel state changes, the element with ID TextLabelID updates its text
    • +
  • Use CollapsedText for text when panel is collapsed
    • +
  • Use ExpandedText for text when panel is expanded
    • +
  • Useful for toggle buttons showing the next action: "▶ Show" vs "▼ Hide"
    • +
+

Expand Direction

+

Vertical (default): +- Panel collapses from bottom up +- Height transitions from full to CollapsedSize +- Best for stacked content

+

Horizontal: +- Panel collapses from right to left +- Width transitions instead of height +- Best for sidebars and menu toggles

+

Auto-Expand/Auto-Collapse

+

When AutoExpand="true": +- Moving mouse into panel automatically expands it +- Useful for hover tooltips or preview panes

+

When AutoCollapse="true": +- Moving mouse out of panel automatically collapses it +- Combines with AutoExpand for full hover support

+

Scrollable Content

+

When ScrollContents="true": +- Overflow content gets scrollbars +- Set ExpandedSize to limit the expanded height +- Useful for log viewers or long content lists

+

Render Mode Requirements

+

The CollapsiblePanelExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+<button ID="btnToggle">Expand</button>
+<div ID="panel">Content</div>
+<CollapsiblePanelExtender TargetControlID="panel" ExpandControlID="btnToggle" />
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The panel remains in its initial display state and doesn't respond to clicks.
    • +
  • JavaScript disabled: Same as SSR — collapse/expand functionality doesn't work.
    • +
  • Module import fails: Any JavaScript errors are logged to browser console; panel remains in initial state.
    • +
+

CSS Considerations

+

For smooth animations, include CSS transitions:

+
#myPanel {
+    transition: height 0.3s ease;
+    overflow: hidden;
+}
+
+

For horizontal collapse: +

#mySidebar {
+    transition: width 0.3s ease;
+    overflow: hidden;
+}
+

+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:CollapsiblePanelExtender
++ <CollapsiblePanelExtender
+

    +
    2. +
  2. +

    Convert ExpandDirection to enum + 

    - ExpandDirection="Vertical"
++ ExpandDirection="ExpandDirection.Vertical"
+

    +
    3. +
  3. +

    Remove runat="server" and ID attributes + 

    - runat="server"
+- ID="cpe"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Button ID="btnToggle" Text="Show Details" runat="server" />
+
+<asp:Panel ID="detailsPanel" style="display: none;">
+    <p>Details content</p>
+</asp:Panel>
+
+<ajaxToolkit:CollapsiblePanelExtender 
+    ID="cpe"
+    TargetControlID="detailsPanel"
+    CollapseControlID="btnToggle"
+    ExpandControlID="btnToggle"
+    CollapsedText="▶ Show"
+    ExpandedText="▼ Hide"
+    TextLabelID="btnToggle"
+    Collapsed="true"
+    runat="server" />
+
+

After (Blazor)

+
<Button ID="btnToggle" Text="Show Details" />
+
+<div ID="detailsPanel" style="display: none;">
+    <p>Details content</p>
+</div>
+
+<CollapsiblePanelExtender 
+    TargetControlID="detailsPanel"
+    CollapseControlID="btnToggle"
+    ExpandControlID="btnToggle"
+    CollapsedText="▶ Show"
+    ExpandedText="▼ Hide"
+    TextLabelID="btnToggle"
+    Collapsed="true" />
+
+

Best Practices

+
    +
  1. Use same button for collapse and expand — Set both CollapseControlID and ExpandControlID to same button ID for toggle behavior
    2. +
  2. Update button text dynamically — Use TextLabelID and CollapsedText/ExpandedText to show user the next action
    3. +
  3. Test with keyboard — Ensure collapse/expand triggers are keyboard-accessible (clickable buttons, not divs)
    4. +
  4. Smooth transitions — Add CSS transition: all 0.3s ease; to panel for smooth animation
    5. +
  5. Avoid nested collapsibles — Nesting multiple CollapsiblePanelExtenders can cause unexpected behavior
    6. +
  6. Use appropriate sizes — CollapsedSize of 0 means fully hidden; use positive values (30-50px) to show a header
    7. +
  7. Set ExpandedSize for auto-sizing — Leave ExpandedSize="0" for auto-height; set explicit value to limit expanded height
    8. +
  8. Accessibility: Use <button> elements for triggers (not <div>), ensure sufficient color contrast, test with screen readers
    9. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Collapse/expand not workingVerify TargetControlID matches panel's ID. Ensure @rendermode InteractiveServer is set. Check browser console for JavaScript errors.
Animation is jerkyVerify target panel has overflow: hidden in CSS. Add transition CSS property to smooth animation.
Text doesn't updateVerify TextLabelID matches the button/element ID. Check that CollapsedText and ExpandedText are set.
Wrong directionVerify ExpandDirection is set correctly. Use ExpandDirection.Vertical for height, ExpandDirection.Horizontal for width.
Auto-collapse/expand not triggeringVerify AutoCollapse="true" and/or AutoExpand="true" are set. Ensure mouse events can reach the panel (check CSS pointer-events).
Panel expands but doesn't collapseCheck that CollapseControlID is set and matches an element ID. Verify trigger element is clickable.
Content runs off-screenSet ExpandedSize to limit expanded height or width. Enable ScrollContents="true" for scrollbars.
Multiple panels collapse togetherEach CollapsiblePanelExtender must have a unique TargetControlID. Avoid reusing panel IDs.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/ConfirmButtonExtender/index.html b/site/AjaxToolkit/ConfirmButtonExtender/index.html new file mode 100644 index 000000000..27dd299be --- /dev/null +++ b/site/AjaxToolkit/ConfirmButtonExtender/index.html @@ -0,0 +1,5314 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ConfirmButtonExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ConfirmButtonExtender

+

The ConfirmButtonExtender displays a browser confirmation dialog when a user clicks a target button. If the user cancels the dialog, the button's click event is suppressed, preventing form submission or callback execution.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/ConfirmButtonExtender

+

Features Supported in Blazor

+
    +
  • ConfirmText — The message displayed in the confirmation dialog
    • +
  • ConfirmOnFormSubmit — Optionally confirm on form submission instead of button click
    • +
  • TargetControlID — ID of the Button to enhance
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Features NOT Supported

+
    +
  • DisplayModalPopupID — Not implemented in v1; reserved for future use (custom modal instead of confirm())
    • +
+

Web Forms Syntax

+
<asp:Button ID="btnDelete" Text="Delete" runat="server" />
+
+<ajaxToolkit:ConfirmButtonExtender 
+    ID="cbe"
+    runat="server"
+    TargetControlID="btnDelete"
+    ConfirmText="Are you sure you want to delete this record?"
+    OnClientCancel="return false;" />
+
+

Blazor Migration

+
<Button ID="btnDelete" Text="Delete" OnClick="HandleDelete" />
+
+<ConfirmButtonExtender 
+    TargetControlID="btnDelete"
+    ConfirmText="Are you sure you want to delete this record?" />
+
+@code {
+    void HandleDelete()
+    {
+        // This only runs if the user clicks OK in the confirm dialog
+    }
+}
+
+

Migration is simple: Just remove the ajaxToolkit: prefix and remove the runat="server" attribute. Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the Button control to enhance
ConfirmTextstring"Are you sure?"The message displayed in the confirmation dialog
ConfirmOnFormSubmitboolfalseIf true, show confirmation on form submission; if false, show on button click
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Confirmation on Click

+
@rendermode InteractiveServer
+
+<Button ID="btnDelete" Text="Delete Record" OnClick="DeleteRecord" />
+
+<ConfirmButtonExtender 
+    TargetControlID="btnDelete"
+    ConfirmText="This will permanently delete the record. Continue?" />
+
+@code {
+    void DeleteRecord()
+    {
+        // This only executes if user clicks OK
+    }
+}
+
+

Confirmation on Form Submission

+

When ConfirmOnFormSubmit is true, the confirmation appears when the user submits the form, regardless of which button they click.

+
@rendermode InteractiveServer
+
+<EditForm Model="@model" OnValidSubmit="HandleSubmit">
+    <InputText @bind-Value="model.Name" placeholder="Name" />
+
+    <Button ID="btnSubmit" Text="Submit" />
+
+    <ConfirmButtonExtender 
+        TargetControlID="btnSubmit"
+        ConfirmText="Are you sure you want to submit this information?"
+        ConfirmOnFormSubmit="true" />
+</EditForm>
+
+@code {
+    private FormModel model = new FormModel();
+
+    void HandleSubmit()
+    {
+        // This executes after user confirms
+    }
+}
+
+

Multiple Buttons with Different Confirmations

+
@rendermode InteractiveServer
+
+<Button ID="btnSave" Text="Save" OnClick="SaveRecord" />
+<Button ID="btnDelete" Text="Delete" OnClick="DeleteRecord" />
+
+<ConfirmButtonExtender 
+    TargetControlID="btnSave"
+    ConfirmText="Save changes?" />
+
+<ConfirmButtonExtender 
+    TargetControlID="btnDelete"
+    ConfirmText="Permanently delete? This cannot be undone." />
+
+@code {
+    void SaveRecord() { /* Save */ }
+    void DeleteRecord() { /* Delete */ }
+}
+
+

Dynamic Confirmation Messages

+
@rendermode InteractiveServer
+
+<Button ID="btnDelete" Text="Delete" OnClick="Delete" />
+
+<ConfirmButtonExtender 
+    TargetControlID="btnDelete"
+    ConfirmText="@GetConfirmMessage()" />
+
+@code {
+    private int recordCount = 0;
+
+    string GetConfirmMessage()
+    {
+        return recordCount == 1
+            ? "Delete 1 record?"
+            : $"Delete {recordCount} records?";
+    }
+
+    void Delete()
+    {
+        // Delete...
+    }
+}
+
+

Destructive Action Pattern

+
@rendermode InteractiveServer
+
+<div style="border: 2px solid red; padding: 1rem; margin-bottom: 1rem;">
+    <h3>Danger Zone</h3>
+    <p>This action cannot be undone.</p>
+
+    <Button ID="btnPermanentDelete" Text="Permanently Delete Account" 
+            CssClass="btn-danger" OnClick="DeleteAccount" />
+
+    <ConfirmButtonExtender 
+        TargetControlID="btnPermanentDelete"
+        ConfirmText="I understand this is permanent. Delete my account?" />
+</div>
+
+@code {
+    void DeleteAccount()
+    {
+        // Account deletion logic
+    }
+}
+
+

HTML Output

+

The ConfirmButtonExtender produces no HTML — it only attaches JavaScript behavior.

+

Before interaction: +

<button type="submit" id="btnDelete">Delete Record</button>
+

+

On click: Browser shows system confirmation dialog: +

Are you sure you want to delete this record?
+[Cancel] [OK]
+

+

If user clicks OK: Button's OnClick handler executes normally. +If user clicks Cancel: Button's OnClick handler is suppressed.

+

Browser Behavior

+

The confirmation dialog is the browser's native confirm() function: +- Shows in the system's native style +- Blocks further JavaScript execution until dismissed +- Cannot be styled with CSS +- Works consistently across all browsers and devices

+

Render Mode Requirements

+

The ConfirmButtonExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+<Button ID="btnDelete" Text="Delete" />
+<ConfirmButtonExtender TargetControlID="btnDelete" ConfirmText="Sure?" />
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization (no error thrown). The button works normally without confirmation.
    • +
  • JavaScript disabled: Same as SSR — button functions without confirmation.
    • +
  • Module import fails: Any JavaScript import errors are logged to browser console; button continues to function.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:ConfirmButtonExtender
++ <ConfirmButtonExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes + 

    - runat="server"
+- ID="cbe"
+

    +
    3. +
  3. +

    Keep all properties the same + 

    TargetControlID="btnDelete"
+ConfirmText="Are you sure?"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Button ID="btnDelete" Text="Delete" OnClick="btnDelete_Click" runat="server" />
+
+<ajaxToolkit:ConfirmButtonExtender 
+    ID="cbe"
+    TargetControlID="btnDelete"
+    ConfirmText="This action cannot be undone. Continue?"
+    runat="server" />
+
+

After (Blazor)

+
<Button ID="btnDelete" Text="Delete" OnClick="HandleDelete" />
+
+<ConfirmButtonExtender 
+    TargetControlID="btnDelete"
+    ConfirmText="This action cannot be undone. Continue?" />
+
+@code {
+    void HandleDelete()
+    {
+        // Handle deletion
+    }
+}
+
+

Best Practices

+
    +
  1. Use for destructive actions — Deletion, account closure, data purge
    2. +
  2. Keep messages clear and short — Users skim confirmation text
    3. +
  3. Include action consequence — Help users make informed decisions
    4. +
  4. Test in your target browsers — Native dialogs vary by browser
    5. +
  5. Provide alternative paths — Allow users to cancel/undo if possible
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Confirmation not appearingVerify TargetControlID matches button's ID. Ensure @rendermode InteractiveServer is set. Check browser console for errors.
Button click always firesCheck that TargetControlID is spelled correctly and matches exactly (case-sensitive).
Multiple confirmations for one clickEnsure only one extender targets each button.
Confirmation appears but ignoredVerify ConfirmText is not empty. Check for JavaScript errors in browser console.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/DragPanelExtender/index.html b/site/AjaxToolkit/DragPanelExtender/index.html new file mode 100644 index 000000000..3864d0bc7 --- /dev/null +++ b/site/AjaxToolkit/DragPanelExtender/index.html @@ -0,0 +1,5169 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DragPanelExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

DragPanelExtender

+

The DragPanelExtender makes a panel or container element draggable. Users can click and drag the panel to reposition it freely on the page. Optionally, a specific handle or title bar can be designated as the drag grip, restricting dragging to that element.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/DragPanelExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the panel or container to make draggable
    • +
  • DragHandleID — Optional ID of the element to use as the drag handle
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Syntax

+
<asp:Panel ID="pnlDialog" runat="server" style="border: 1px solid black; width: 300px;">
+    <div id="pnlHeader" style="background-color: #333; padding: 5px;">
+        <h3>My Dialog</h3>
+    </div>
+    <div style="padding: 10px;">
+        <p>Drag me by the header!</p>
+    </div>
+</asp:Panel>
+
+<ajaxToolkit:DragPanelExtender
+    ID="drag1"
+    runat="server"
+    TargetControlID="pnlDialog"
+    DragHandleID="pnlHeader" />
+
+

Blazor Migration

+
<Panel ID="pnlDialog" style="border: 1px solid black; width: 300px;">
+    <div id="pnlHeader" style="background-color: #333; padding: 5px;">
+        <h3>My Dialog</h3>
+    </div>
+    <div style="padding: 10px;">
+        <p>Drag me by the header!</p>
+    </div>
+</Panel>
+
+<DragPanelExtender
+    TargetControlID="pnlDialog"
+    DragHandleID="pnlHeader" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the panel or container to make draggable
DragHandleIDstring""Optional ID of an element to use as the drag handle; if not set, entire panel is draggable
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Draggable Entire Panel

+
@rendermode InteractiveServer
+
+<Panel ID="pnlBox" style="width: 300px; border: 1px solid #ccc; padding: 10px; background: white; cursor: move;">
+    <p>Drag this panel anywhere!</p>
+</Panel>
+
+<DragPanelExtender TargetControlID="pnlBox" />
+
+

Draggable with Handle

+
@rendermode InteractiveServer
+
+<Panel ID="pnlWindow" style="width: 400px; border: 1px solid black;">
+    <div id="titleBar" style="background-color: #4CAF50; color: white; padding: 10px; cursor: move;">
+        Window Title
+    </div>
+    <div style="padding: 20px; background-color: white;">
+        <p>This can only be dragged by the title bar.</p>
+    </div>
+</Panel>
+
+<DragPanelExtender
+    TargetControlID="pnlWindow"
+    DragHandleID="titleBar" />
+
+

Floating Dialog Box

+
@rendermode InteractiveServer
+
+<Panel ID="pnlDialog" style="position: absolute; top: 100px; left: 100px; width: 350px; border: 1px solid #999; box-shadow: 0 2px 5px rgba(0,0,0,0.2); background: white;">
+    <div id="dialogHeader" style="background: linear-gradient(to right, #2196F3, #1976D2); color: white; padding: 10px; font-weight: bold; cursor: move;">
+        Settings
+    </div>
+    <div style="padding: 20px;">
+        <form>
+            <input type="checkbox" /> Enable notifications
+            <br /><br />
+            <button type="button" class="btn btn-primary">Save</button>
+        </form>
+    </div>
+</Panel>
+
+<DragPanelExtender
+    TargetControlID="pnlDialog"
+    DragHandleID="dialogHeader" />
+
+

HTML Output

+

The DragPanelExtender produces no HTML itself — it attaches JavaScript behavior to the target panel. The panel retains its original HTML structure and styling.

+

JavaScript Interop

+

The DragPanelExtender loads drag-panel-extender.js as an ES module. JavaScript handles:

+
    +
  • Detecting mouse down on the panel or handle
    • +
  • Tracking mouse movement while dragging
    • +
  • Updating the panel's position in real-time
    • +
  • Handling mouse up to stop dragging
    • +
  • Managing z-index to keep dragged panel on top
    • +
  • Preventing text selection during drag
    • +
+

Render Mode Requirements

+

The DragPanelExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The Panel displays statically.
    • +
  • JavaScript disabled: Same as SSR — Panel is not draggable.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:DragPanelExtender
++ <DragPanelExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Panel element stays the same + 

    - <asp:Panel ID="pnlDialog" runat="server">
++ <Panel ID="pnlDialog">
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Panel ID="pnlDialog" runat="server" style="width: 300px; border: 1px solid black;">
+    <div id="header" style="background: #333; color: white; padding: 5px; cursor: move;">Title</div>
+    <div style="padding: 10px;">Content</div>
+</asp:Panel>
+
+<ajaxToolkit:DragPanelExtender
+    ID="drag1"
+    TargetControlID="pnlDialog"
+    DragHandleID="header"
+    runat="server" />
+
+

After (Blazor)

+
<Panel ID="pnlDialog" style="width: 300px; border: 1px solid black;">
+    <div id="header" style="background: #333; color: white; padding: 5px; cursor: move;">Title</div>
+    <div style="padding: 10px;">Content</div>
+</Panel>
+
+<DragPanelExtender
+    TargetControlID="pnlDialog"
+    DragHandleID="header" />
+
+

Best Practices

+
    +
  1. Set position: absolute — Use CSS to position the panel before dragging starts
    2. +
  2. Use a handle — Provide a DragHandleID to prevent accidental dragging of content
    3. +
  3. Apply cursor: move — Use CSS to indicate the element is draggable
    4. +
  4. Preserve boundaries — Monitor panel position to keep it within viewport
    5. +
  5. Apply z-index — Ensure dragged panels appear above other page content
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Panel not draggableVerify TargetControlID matches the Panel's ID. Ensure @rendermode InteractiveServer is set.
Dragging causes text selectionAdd user-select: none CSS or use DragHandleID to restrict dragging to a specific element.
Handle not working as expectedEnsure DragHandleID references a valid element within the panel with the correct ID.
Panel disappears during dragCheck z-index values and ensure the panel's position is compatible with absolute positioning.
+

See Also

+
    +
  • Ajax Control Toolkit Overview — How extenders work and render mode requirements
    • +
  • Panel Component — The Panel control (documentation coming soon)
    • +
  • ResizableControlExtender — Make panels resizable
    • +
  • Original Ajax Control Toolkit: https://www.asp.net/ajax/ajaxcontroltoolkit
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/DropShadowExtender/index.html b/site/AjaxToolkit/DropShadowExtender/index.html new file mode 100644 index 000000000..d7780bb9d --- /dev/null +++ b/site/AjaxToolkit/DropShadowExtender/index.html @@ -0,0 +1,5244 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DropShadowExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

DropShadowExtender

+

The DropShadowExtender adds a drop shadow effect to an element, giving it a raised or floating appearance. The shadow can be customized with opacity, width, corner rounding, and can optionally track the element's position as it moves.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/DropShadowExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the element to add a drop shadow to
    • +
  • Opacity — Shadow opacity from 0.0 (transparent) to 1.0 (opaque)
    • +
  • Width — Shadow width in pixels
    • +
  • Rounded — Whether to round the corners of the target element
    • +
  • Radius — Corner radius in pixels when Rounded is true
    • +
  • TrackPosition — Whether the shadow tracks the element's position if it moves
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Syntax

+
<asp:Panel ID="pnlBox" runat="server" style="width: 300px; padding: 15px; background-color: white;">
+    <h3>Floating Panel</h3>
+    <p>This panel has a drop shadow.</p>
+</asp:Panel>
+
+<ajaxToolkit:DropShadowExtender
+    ID="shadow1"
+    runat="server"
+    TargetControlID="pnlBox"
+    Opacity="0.5"
+    Width="5"
+    Rounded="true"
+    Radius="10" />
+
+

Blazor Migration

+
<Panel ID="pnlBox" style="width: 300px; padding: 15px; background-color: white;">
+    <h3>Floating Panel</h3>
+    <p>This panel has a drop shadow.</p>
+</Panel>
+
+<DropShadowExtender
+    TargetControlID="pnlBox"
+    Opacity="0.5"
+    Width="5"
+    Rounded="true"
+    Radius="10" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the element to add a drop shadow to
Opacitydouble0.5Shadow opacity from 0.0 (fully transparent) to 1.0 (fully opaque)
Widthint5Shadow width in pixels
RoundedboolfalseWhether to round the corners of the target element
Radiusint0Corner radius in pixels when Rounded is true
TrackPositionboolfalseWhether the shadow should track the element's position if it moves
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Drop Shadow

+
@rendermode InteractiveServer
+
+<Panel ID="pnlCard" style="width: 250px; padding: 20px; background-color: white;">
+    <h3>Card Title</h3>
+    <p>This card has a subtle drop shadow.</p>
+</Panel>
+
+<DropShadowExtender
+    TargetControlID="pnlCard"
+    Opacity="0.5"
+    Width="5" />
+
+

Shadow with Rounded Corners

+
@rendermode InteractiveServer
+
+<Panel ID="pnlRounded" style="width: 300px; padding: 20px; background-color: #f9f9f9;">
+    <h3>Rounded Panel</h3>
+    <p>This panel has both rounded corners and a drop shadow.</p>
+</Panel>
+
+<DropShadowExtender
+    TargetControlID="pnlRounded"
+    Opacity="0.6"
+    Width="8"
+    Rounded="true"
+    Radius="15" />
+
+

Prominent Shadow Effect

+
@rendermode InteractiveServer
+
+<Panel ID="pnlHighlight" style="width: 350px; padding: 25px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white;">
+    <h2>Featured Content</h2>
+    <p>This panel uses a prominent shadow for emphasis.</p>
+</Panel>
+
+<DropShadowExtender
+    TargetControlID="pnlHighlight"
+    Opacity="0.8"
+    Width="12"
+    Rounded="true"
+    Radius="10" />
+
+

Shadow with Position Tracking

+
@rendermode InteractiveServer
+
+<Panel ID="pnlDynamic" style="width: 300px; padding: 20px; background-color: white; position: absolute; top: 50px; left: 50px;">
+    <h3>Dynamic Position</h3>
+    <p>This panel's shadow follows its position.</p>
+</Panel>
+
+<DropShadowExtender
+    TargetControlID="pnlDynamic"
+    Opacity="0.7"
+    Width="6"
+    TrackPosition="true" />
+
+<script>
+    // Move the panel around and the shadow follows
+    var panel = document.getElementById('pnlDynamic');
+    var offset = 10;
+    function movePanel() {
+        panel.style.top = (50 + offset) + 'px';
+        panel.style.left = (50 + offset) + 'px';
+        offset = (offset === 10) ? 20 : 10;
+    }
+</script>
+
+

HTML Output

+

The DropShadowExtender produces a shadow element (typically a <div>) positioned behind the target element. The original element structure remains unchanged.

+

JavaScript Interop

+

The DropShadowExtender loads drop-shadow-extender.js as an ES module. JavaScript handles:

+
    +
  • Creating shadow DOM elements
    • +
  • Positioning shadows relative to the target
    • +
  • Applying opacity and width settings
    • +
  • Optional corner rounding with CSS
    • +
  • Tracking element position if TrackPosition is enabled
    • +
  • Responsive shadow updates on window resize
    • +
+

Render Mode Requirements

+

The DropShadowExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The element displays without a shadow.
    • +
  • JavaScript disabled: Same as SSR — Shadow is not rendered.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:DropShadowExtender
++ <DropShadowExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Shadow properties stay the same + 

    - Opacity="0.5"
++ Opacity="0.5"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Panel ID="pnlBox" runat="server" style="width: 300px; padding: 15px; background: white;">
+    <p>Card content</p>
+</asp:Panel>
+
+<ajaxToolkit:DropShadowExtender
+    ID="shadow1"
+    TargetControlID="pnlBox"
+    Opacity="0.5"
+    Width="5"
+    Rounded="true"
+    Radius="10"
+    runat="server" />
+
+

After (Blazor)

+
<Panel ID="pnlBox" style="width: 300px; padding: 15px; background: white;">
+    <p>Card content</p>
+</Panel>
+
+<DropShadowExtender
+    TargetControlID="pnlBox"
+    Opacity="0.5"
+    Width="5"
+    Rounded="true"
+    Radius="10" />
+
+

Best Practices

+
    +
  1. Use subtle opacity — Opacity between 0.4 and 0.6 typically looks best
    2. +
  2. Match shadow width to design — Narrow shadows (3-5px) for subtle effects, wider (8-12px) for emphasis
    3. +
  3. Enable rounding for modern look — Combine Rounded="true" with appropriate Radius
    4. +
  4. Use TrackPosition for dynamic elements — Enable if the element will change position via JavaScript
    5. +
  5. Test on different backgrounds — Shadows appear differently on light vs. dark backgrounds
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Shadow not visibleVerify TargetControlID matches the element's ID. Ensure @rendermode InteractiveServer is set.
Shadow too faintIncrease Opacity (try 0.7 or 0.8) or increase Width for a more visible effect.
Shadow not following elementIf the element moves via JavaScript, enable TrackPosition="true".
Performance issuesReduce Opacity and Width values, or disable TrackPosition if not needed.
+

See Also

+
    +
  • Ajax Control Toolkit Overview — How extenders work and render mode requirements
    • +
  • Panel Component — The Panel control (documentation coming soon)
    • +
  • RoundedCornersExtender — Apply rounded corners to elements
    • +
  • Original Ajax Control Toolkit: https://www.asp.net/ajax/ajaxcontroltoolkit
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/FilteredTextBoxExtender/index.html b/site/AjaxToolkit/FilteredTextBoxExtender/index.html new file mode 100644 index 000000000..b884fc52d --- /dev/null +++ b/site/AjaxToolkit/FilteredTextBoxExtender/index.html @@ -0,0 +1,5732 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FilteredTextBoxExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

FilteredTextBoxExtender

+

The FilteredTextBoxExtender restricts input in a TextBox to specified character types. It filters keystrokes in real-time and automatically strips invalid characters on paste operations, ensuring only allowed characters appear in the input.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/FilteredTextBoxExtender

+

Features Supported in Blazor

+
    +
  • FilterType — Combination of Numbers, UppercaseLetters, LowercaseLetters, and Custom
    • +
  • ValidChars — Additional allowed characters when FilterType includes Custom
    • +
  • InvalidChars — Characters to explicitly block
    • +
  • FilterMode — Whether to use ValidChars (whitelist) or InvalidChars (blacklist)
    • +
  • FilterInterval — Milliseconds between filter checks (default: 250ms)
    • +
  • TargetControlID — ID of the TextBox to enhance
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

FilterType and FilterMode Enums

+

FilterType (Flags Enum)

+

Character types can be combined using the bitwise OR operator (|):

+
enum FilterType
+{
+    Custom = 0,              // No predefined characters
+    Numbers = 1,             // Digits 0-9
+    LowercaseLetters = 2,    // a-z
+    UppercaseLetters = 4     // A-Z
+}
+
+

FilterMode

+

Determines whether ValidChars or InvalidChars takes precedence:

+
enum FilterMode
+{
+    ValidChars = 0,    // Whitelist: only these characters allowed
+    InvalidChars = 1   // Blacklist: these characters blocked
+}
+
+

Web Forms Syntax

+
<asp:TextBox ID="txtPhone" runat="server" />
+
+<ajaxToolkit:FilteredTextBoxExtender 
+    ID="ftb"
+    TargetControlID="txtPhone"
+    FilterType="Numbers"
+    runat="server" />
+
+<!-- Phone number with dashes and parentheses -->
+<asp:TextBox ID="txtPhoneFormatted" runat="server" />
+
+<ajaxToolkit:FilteredTextBoxExtender 
+    ID="ftb2"
+    TargetControlID="txtPhoneFormatted"
+    FilterType="Numbers, Custom"
+    ValidChars="()-"
+    runat="server" />
+
+

Blazor Migration

+
<TextBox @bind-Text="phone" ID="txtPhone" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtPhone"
+    FilterType="FilterType.Numbers" />
+
+<!-- Phone number with dashes and parentheses -->
+<TextBox @bind-Text="phoneFormatted" ID="txtPhoneFormatted" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtPhoneFormatted"
+    FilterType="FilterType.Numbers | FilterType.Custom"
+    ValidChars="()-" />
+
+@code {
+    private string phone = "";
+    private string phoneFormatted = "";
+}
+
+

Migration is simple: Just remove the ajaxToolkit: prefix and convert enum values to FilterType.EnumName syntax.

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the TextBox control to enhance
FilterTypeFilterTypeCustomTypes of characters to allow (use \| to combine)
ValidCharsstring""Additional characters allowed when FilterType includes Custom
InvalidCharsstring""Characters to explicitly block (only used with InvalidChars mode)
FilterModeFilterModeValidCharsWhether ValidChars or InvalidChars takes precedence
FilterIntervalint250Milliseconds between filter checks
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Numbers Only

+
@rendermode InteractiveServer
+
+<TextBox @bind-Text="quantity" ID="txtQty" placeholder="Enter quantity" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtQty"
+    FilterType="FilterType.Numbers" />
+
+@code {
+    private string quantity = "";
+}
+
+

Uppercase Letters Only

+
@rendermode InteractiveServer
+
+<TextBox @bind-Text="code" ID="txtCode" MaxLength="10" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtCode"
+    FilterType="FilterType.UppercaseLetters" />
+
+@code {
+    private string code = "";
+}
+
+

Phone Number (Numbers, Dashes, Parentheses)

+
@rendermode InteractiveServer
+
+<TextBox @bind-Text="phone" ID="txtPhone" placeholder="(555) 123-4567" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtPhone"
+    FilterType="FilterType.Numbers | FilterType.Custom"
+    ValidChars="()-" />
+
+@code {
+    private string phone = "";
+}
+
+

Alphanumeric (Letters and Numbers)

+
@rendermode InteractiveServer
+
+<TextBox @bind-Text="username" ID="txtUsername" placeholder="Your username" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtUsername"
+    FilterType="FilterType.Numbers | FilterType.UppercaseLetters | FilterType.LowercaseLetters" />
+
+@code {
+    private string username = "";
+}
+
+

Currency (Numbers and Decimal Point)

+
@rendermode InteractiveServer
+
+<TextBox @bind-Text="price" ID="txtPrice" placeholder="0.00" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtPrice"
+    FilterType="FilterType.Numbers | FilterType.Custom"
+    ValidChars="." />
+
+@code {
+    private string price = "";
+}
+
+

Product SKU (Alphanumeric and Hyphens)

+
@rendermode InteractiveServer
+
+<TextBox @bind-Text="sku" ID="txtSKU" placeholder="SKU-1234-5678" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtSKU"
+    FilterType="FilterType.Numbers | FilterType.UppercaseLetters | FilterType.Custom"
+    ValidChars="-" />
+
+@code {
+    private string sku = "";
+}
+
+

Block Certain Characters (Blacklist)

+

Using InvalidChars mode to block specific characters:

+
@rendermode InteractiveServer
+
+<TextBox @bind-Text="filename" ID="txtFileName" placeholder="Enter filename" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtFileName"
+    FilterType="FilterType.Numbers | FilterType.UppercaseLetters | FilterType.LowercaseLetters"
+    InvalidChars="<>:/\|?*"
+    FilterMode="FilterMode.InvalidChars" />
+
+@code {
+    private string filename = "";
+}
+
+

Slow Filter Interval (Performance Tuning)

+

For high-performance scenarios, increase the filter interval:

+
@rendermode InteractiveServer
+
+<TextBox @bind-Text="data" ID="txtData" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtData"
+    FilterType="FilterType.Numbers"
+    FilterInterval="500" />
+
+@code {
+    private string data = "";
+}
+
+

HTML Output

+

The FilteredTextBoxExtender produces no HTML — it only attaches JavaScript behavior to the target TextBox.

+

Before (TextBox markup): +

<input type="text" id="txtPhone" value="" />
+

+

After (with FilteredTextBoxExtender attached): +

<input type="text" id="txtPhone" value="" />
+<!-- JavaScript behavior injected; user cannot type invalid characters -->
+

+

Filtering Behavior

+

Real-Time Keystroke Filtering

+
    +
  • Invalid characters are prevented at keystroke
    • +
  • User never sees the invalid character in the input
    • +
  • Works on keyboard input, arrow keys, delete, backspace, etc.
    • +
+

Paste Handling

+
    +
  • When user pastes content, the extender automatically strips invalid characters
    • +
  • Only valid characters from the paste are inserted
    • +
  • Example: Pasting "abc123def" into a Numbers-only field results in "123"
    • +
+

Backspace and Delete

+
    +
  • Backspace and Delete work normally
    • +
  • They are not subject to filtering
    • +
  • Allows users to correct mistakes naturally
    • +
+

Character Set Combinations

+

Common Patterns

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Use CaseFilterTypeValidChars
Numbers onlyNumbers-
Integers and decimalsNumbers. (with Custom)
Currency (USD)Numbers.-$ (with Custom)
Phone (US)Numbers()-+ (with Custom)
EmailLowercaseLetters \| Numbers.@-_ (with Custom)
UsernameUppercaseLetters \| LowercaseLetters \| Numbers-_ (with Custom)
ZIP codeNumbers- (with Custom, for ZIP+4)
License plateUppercaseLetters \| Numbers- (with Custom)
+

Custom Patterns

+
@* Portuguese characters *@
+<FilteredTextBoxExtender 
+    TargetControlID="txtPortuguese"
+    FilterType="FilterType.LowercaseLetters | FilterType.UppercaseLetters | FilterType.Custom"
+    ValidChars="áéíóúàâêôãõç" />
+
+@* Mathematical expression *@
+<FilteredTextBoxExtender 
+    TargetControlID="txtMath"
+    FilterType="FilterType.Numbers | FilterType.Custom"
+    ValidChars="+-*/(). " />
+
+

Render Mode Requirements

+

The FilteredTextBoxExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+<TextBox @bind-Text="input" ID="txtInput" />
+<FilteredTextBoxExtender 
+    TargetControlID="txtInput"
+    FilterType="FilterType.Numbers" />
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The TextBox works normally without filtering (all input accepted).
    • +
  • JavaScript disabled: Same as SSR — TextBox accepts all input.
    • +
  • Module import fails: Any JavaScript errors are logged to browser console; TextBox continues to function normally.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:FilteredTextBoxExtender
++ <FilteredTextBoxExtender
+

    +
    2. +
  2. +

    Convert FilterType flags from space-separated to C# bitwise OR + 

    - FilterType="Numbers, Custom"
++ FilterType="FilterType.Numbers | FilterType.Custom"
+

    +
    3. +
  3. +

    Remove runat="server" and ID attributes + 

    - runat="server"
+- ID="ftb"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtPhone" runat="server" MaxLength="14" />
+
+<ajaxToolkit:FilteredTextBoxExtender 
+    ID="ftbPhone"
+    TargetControlID="txtPhone"
+    FilterType="Numbers, Custom"
+    ValidChars="()-"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox @bind-Text="phone" ID="txtPhone" MaxLength="14" />
+
+<FilteredTextBoxExtender 
+    TargetControlID="txtPhone"
+    FilterType="FilterType.Numbers | FilterType.Custom"
+    ValidChars="()-" />
+
+@code {
+    private string phone = "";
+}
+
+

Best Practices

+
    +
  1. Use ValidChars mode for precision — Whitelist known-good characters (safer than blacklist)
    2. +
  2. Combine multiple FilterTypes — Use | operator: FilterType.Numbers | FilterType.LowercaseLetters
    3. +
  3. Test paste operations — Users will try to paste; verify the behavior matches expectations
    4. +
  4. Provide clear placeholders — Show users what format is expected: placeholder="(555) 123-4567"
    5. +
  5. Server-side validation — Never rely on client-side filtering alone; always validate on the server
    6. +
  6. Consider masking — For structured data (phone, date, SSN), consider input masks in addition to filtering
    7. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Filtering not workingVerify TargetControlID matches TextBox's ID. Ensure @rendermode InteractiveServer is set. Check browser console for JavaScript errors.
Wrong characters allowedVerify FilterType flags and ValidChars are correct. Remember: FilterType.Custom requires ValidChars to be set.
Pasted content not filteredThis is expected if InvalidChars mode is used. Switch to ValidChars mode (default) for stricter control.
Users cannot paste at allCheck that valid characters from the paste exist in your filter. If pasting "abc" into a Numbers-only field, nothing will paste (empty result).
Performance issues with rapid inputIncrease FilterInterval to reduce checking frequency (default 250ms).
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/HoverMenuExtender/index.html b/site/AjaxToolkit/HoverMenuExtender/index.html new file mode 100644 index 000000000..3fcc8a6ab --- /dev/null +++ b/site/AjaxToolkit/HoverMenuExtender/index.html @@ -0,0 +1,5334 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + HoverMenuExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

HoverMenuExtender

+

The HoverMenuExtender displays a popup panel when the user hovers over a target control. It supports configurable show/hide delays, positional placement, and hover CSS styling. The popup remains visible while the mouse is over either the target or the popup itself.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/HoverMenuExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the control that triggers the hover menu
    • +
  • PopupControlID — ID of the panel element to display as a hover menu
    • +
  • PopupPosition — Position of the popup relative to the target
    • +
  • OffsetX — Horizontal offset in pixels from the calculated position
    • +
  • OffsetY — Vertical offset in pixels from the calculated position
    • +
  • PopDelay — Delay in milliseconds before showing the popup
    • +
  • HoverDelay — Delay in milliseconds before hiding the popup
    • +
  • HoverCssClass — CSS class applied to the target while the hover menu is visible
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

PopupPosition Enum

+
enum PopupPosition
+{
+    Left = 0,     // To the left of target
+    Right = 1,    // To the right of target (default for HoverMenuExtender)
+    Top = 2,      // Above target
+    Bottom = 3,   // Below target
+    Center = 4    // Centered on target
+}
+
+

Web Forms Syntax

+
<asp:Panel ID="pnlRow" runat="server" CssClass="data-row">
+    <span>Row content here</span>
+</asp:Panel>
+
+<asp:Panel ID="pnlActions" runat="server" style="display: none;" CssClass="hover-actions">
+    <asp:Button ID="btnEdit" Text="Edit" runat="server" />
+    <asp:Button ID="btnDelete" Text="Delete" runat="server" />
+</asp:Panel>
+
+<ajaxToolkit:HoverMenuExtender
+    ID="hme1"
+    runat="server"
+    TargetControlID="pnlRow"
+    PopupControlID="pnlActions"
+    PopupPosition="Right"
+    HoverDelay="200"
+    PopDelay="100"
+    HoverCssClass="row-hover"
+    OffsetX="5" />
+
+

Blazor Migration

+
<div ID="pnlRow" class="data-row">
+    <span>Row content here</span>
+</div>
+
+<div ID="pnlActions" style="display: none;" class="hover-actions">
+    <Button ID="btnEdit" Text="Edit" />
+    <Button ID="btnDelete" Text="Delete" />
+</div>
+
+<HoverMenuExtender
+    TargetControlID="pnlRow"
+    PopupControlID="pnlActions"
+    PopupPosition="PopupPosition.Right"
+    HoverDelay="200"
+    PopDelay="100"
+    HoverCssClass="row-hover"
+    OffsetX="5" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Use full enum type name for PopupPosition. Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the control that triggers the hover menu
PopupControlIDstring""ID of the panel element to display as a hover menu
PopupPositionPopupPositionRightPosition of the popup relative to the target: Left, Right, Top, Bottom, Center
OffsetXint0Horizontal offset in pixels from the calculated position
OffsetYint0Vertical offset in pixels from the calculated position
PopDelayint0Delay in milliseconds before showing the popup after mouse enters the target
HoverDelayint300Delay in milliseconds before hiding the popup after mouse leaves the target and popup
HoverCssClassstring""CSS class applied to the target control while the hover menu is visible
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Hover Menu

+
@rendermode InteractiveServer
+
+<div ID="targetItem" style="padding: 10px; border: 1px solid #ddd; cursor: pointer;">
+    Hover over me to see actions
+</div>
+
+<div ID="hoverPanel" style="display: none; background: white; border: 1px solid #ccc; padding: 10px; box-shadow: 0 2px 8px rgba(0,0,0,0.15);">
+    <button>Edit</button>
+    <button>Delete</button>
+    <button>Share</button>
+</div>
+
+<HoverMenuExtender
+    TargetControlID="targetItem"
+    PopupControlID="hoverPanel"
+    PopupPosition="PopupPosition.Right"
+    HoverDelay="200" />
+
+

Row Actions on Hover

+
@rendermode InteractiveServer
+
+@foreach (var item in items)
+{
+    <div ID="@($"row-{item.Id}")" class="list-row">
+        <span>@item.Name</span>
+    </div>
+
+    <div ID="@($"actions-{item.Id}")" style="display: none;" class="action-panel">
+        <button onclick="@(() => Edit(item.Id))">✏️ Edit</button>
+        <button onclick="@(() => Delete(item.Id))">🗑️ Delete</button>
+    </div>
+
+    <HoverMenuExtender
+        TargetControlID="@($"row-{item.Id}")"
+        PopupControlID="@($"actions-{item.Id}")"
+        PopupPosition="PopupPosition.Right"
+        HoverDelay="300"
+        HoverCssClass="row-highlighted"
+        OffsetX="10" />
+}
+
+<style>
+    .list-row { padding: 10px; border-bottom: 1px solid #eee; }
+    .row-highlighted { background: #f0f8ff; }
+    .action-panel { background: white; border: 1px solid #ddd; padding: 8px; border-radius: 4px; }
+</style>
+
+@code {
+    private List<Item> items = new();
+    void Edit(int id) { /* Edit logic */ }
+    void Delete(int id) { /* Delete logic */ }
+}
+
+

Tooltip-Style Hover Menu

+
@rendermode InteractiveServer
+
+<span ID="helpIcon" style="cursor: help; font-size: 1.2em;">ℹ️</span>
+
+<div ID="helpTooltip" style="display: none; background: #333; color: white; padding: 12px; border-radius: 6px; max-width: 250px; font-size: 0.9em;">
+    <p>This field accepts values between 1 and 100. Leave blank for the default value.</p>
+</div>
+
+<HoverMenuExtender
+    TargetControlID="helpIcon"
+    PopupControlID="helpTooltip"
+    PopupPosition="PopupPosition.Bottom"
+    PopDelay="200"
+    HoverDelay="500"
+    OffsetY="5" />
+
+

Hover Menu with Show Delay

+
@rendermode InteractiveServer
+
+<div ID="menuTrigger" style="padding: 8px 16px; background: #007bff; color: white; display: inline-block; border-radius: 4px;">
+    More Options ▼
+</div>
+
+<div ID="menuPopup" style="display: none; background: white; border: 1px solid #ddd; min-width: 150px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);">
+    <div style="padding: 8px 16px; cursor: pointer;">Option 1</div>
+    <div style="padding: 8px 16px; cursor: pointer;">Option 2</div>
+    <div style="padding: 8px 16px; cursor: pointer;">Option 3</div>
+</div>
+
+<HoverMenuExtender
+    TargetControlID="menuTrigger"
+    PopupControlID="menuPopup"
+    PopupPosition="PopupPosition.Bottom"
+    PopDelay="100"
+    HoverDelay="400" />
+
+

HTML Output

+

The HoverMenuExtender produces no HTML itself — it attaches JavaScript behavior to show/hide the popup panel on mouse enter/leave events.

+

JavaScript Interop

+

The HoverMenuExtender loads hover-menu-extender.js as an ES module. JavaScript handles:

+
    +
  • Monitoring mouse enter/leave events on the target and popup elements
    • +
  • Applying show/hide delays (PopDelay and HoverDelay)
    • +
  • Positioning the popup relative to the target with offsets
    • +
  • Adding/removing the HoverCssClass on the target element
    • +
  • Keeping the popup visible when the mouse moves between target and popup
    • +
+

Render Mode Requirements

+

The HoverMenuExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The popup panel remains hidden.
    • +
  • JavaScript disabled: Same as SSR — target control functions normally without hover behavior.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:HoverMenuExtender
++ <HoverMenuExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use full enum type name for PopupPosition + 

    - PopupPosition="Right"
++ PopupPosition="PopupPosition.Right"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Panel ID="pnlTarget" runat="server">
+    <span>Hover me</span>
+</asp:Panel>
+
+<asp:Panel ID="pnlMenu" runat="server" style="display: none;">
+    <a href="#">Edit</a> | <a href="#">Delete</a>
+</asp:Panel>
+
+<ajaxToolkit:HoverMenuExtender
+    ID="hme1"
+    TargetControlID="pnlTarget"
+    PopupControlID="pnlMenu"
+    PopupPosition="Right"
+    HoverDelay="200"
+    runat="server" />
+
+

After (Blazor)

+
<div ID="pnlTarget">
+    <span>Hover me</span>
+</div>
+
+<div ID="pnlMenu" style="display: none;">
+    <a href="#">Edit</a> | <a href="#">Delete</a>
+</div>
+
+<HoverMenuExtender
+    TargetControlID="pnlTarget"
+    PopupControlID="pnlMenu"
+    PopupPosition="PopupPosition.Right"
+    HoverDelay="200" />
+
+

Best Practices

+
    +
  1. Set appropriate delays — PopDelay of 100–200ms prevents accidental triggers; HoverDelay of 200–500ms gives users time to reach the popup
    2. +
  2. Hide the popup initially — Set style="display: none;" on the popup element
    3. +
  3. Use HoverCssClass — Highlight the target to show the hover menu is active
    4. +
  4. Position wisely — Use Right or Bottom for most use cases; adjust with offsets
    5. +
  5. Keep popup content interactive — Users should be able to interact with buttons/links in the popup
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Popup not appearingVerify TargetControlID and PopupControlID match their elements' IDs. Ensure @rendermode InteractiveServer is set.
Popup disappears too quicklyIncrease HoverDelay to give users more time (300–500ms).
Popup appears too slowlyDecrease PopDelay (0–100ms).
Popup positioned incorrectlyTry a different PopupPosition value or adjust OffsetX/OffsetY.
HoverCssClass not appliedVerify the CSS class name is correct and the styles are defined.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/ListSearchExtender/index.html b/site/AjaxToolkit/ListSearchExtender/index.html new file mode 100644 index 000000000..ab393bed6 --- /dev/null +++ b/site/AjaxToolkit/ListSearchExtender/index.html @@ -0,0 +1,5352 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ListSearchExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ListSearchExtender

+

The ListSearchExtender enables search and filter functionality on a ListBox or DropDownList control. As the user types in a search field, items that don't match are filtered, or if auto-select is enabled, the selection jumps to the first matching item. Supports configurable search patterns (Contains or StartsWith) and sorted list optimization.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/ListSearchExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the ListBox or DropDownList to search
    • +
  • PromptText — Placeholder text for the search input
    • +
  • PromptCssClass — CSS class for search prompt styling
    • +
  • PromptPosition — Where to position the search prompt (Top, Bottom)
    • +
  • IsSorted — Whether list items are sorted for optimized binary search
    • +
  • QueryPattern — Search pattern type (Contains, StartsWith)
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

PromptPosition Enum

+

Controls search prompt placement:

+
enum PromptPosition
+{
+    Top = 0,
+    Bottom = 1
+}
+
+

QueryPattern Enum

+

Controls search matching:

+
enum QueryPattern
+{
+    Contains = 0,    // Match anywhere in text
+    StartsWith = 1   // Match from beginning only
+}
+
+

Web Forms Syntax

+
<asp:ListBox ID="lstCountries" runat="server" Height="150px">
+    <asp:ListItem>Afghanistan</asp:ListItem>
+    <asp:ListItem>Albania</asp:ListItem>
+    <asp:ListItem>Algeria</asp:ListItem>
+    <!-- ... more items ... -->
+</asp:ListBox>
+
+<ajaxToolkit:ListSearchExtender
+    ID="search1"
+    runat="server"
+    TargetControlID="lstCountries"
+    PromptText="Type to search..."
+    PromptPosition="Top"
+    IsSorted="true"
+    QueryPattern="StartsWith" />
+
+

Blazor Migration

+
<ListBox ID="lstCountries" style="height: 150px;">
+    <ListItem>Afghanistan</ListItem>
+    <ListItem>Albania</ListItem>
+    <ListItem>Algeria</ListItem>
+    <!-- ... more items ... -->
+</ListBox>
+
+<ListSearchExtender
+    TargetControlID="lstCountries"
+    PromptText="Type to search..."
+    PromptPosition="PromptPosition.Top"
+    IsSorted="true"
+    QueryPattern="QueryPattern.StartsWith" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Use enum type names!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the ListBox or DropDownList to search
PromptTextstring"Type to search"Placeholder text shown in the search input when empty
PromptCssClassstring""CSS class applied to the search prompt text
PromptPositionPromptPositionTopWhere to display the search prompt relative to the list
IsSortedboolfalseWhether list items are sorted; enables optimized binary search
QueryPatternQueryPatternContainsSearch pattern type (Contains matches anywhere, StartsWith from beginning)
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+ +
@rendermode InteractiveServer
+
+<div>
+    <label>Select a Country:</label>
+
+    <ListBox ID="lstCountries" style="width: 200px; height: 200px;">
+        <ListItem>Afghanistan</ListItem>
+        <ListItem>Albania</ListItem>
+        <ListItem>Algeria</ListItem>
+        <ListItem>Andorra</ListItem>
+        <ListItem>Angola</ListItem>
+        <ListItem>Argentina</ListItem>
+        <!-- ... more countries ... -->
+    </ListBox>
+
+    <ListSearchExtender
+        TargetControlID="lstCountries"
+        PromptText="Search countries..."
+        PromptPosition="PromptPosition.Top"
+        IsSorted="true"
+        QueryPattern="QueryPattern.StartsWith" />
+</div>
+
+ +
@rendermode InteractiveServer
+
+<div>
+    <label>Select a State:</label>
+
+    <DropDownList ID="ddlStates" style="width: 200px;">
+        <ListItem Value="">-- Select a State --</ListItem>
+        <ListItem Value="AL">Alabama</ListItem>
+        <ListItem Value="AK">Alaska</ListItem>
+        <ListItem Value="AZ">Arizona</ListItem>
+        <ListItem Value="AR">Arkansas</ListItem>
+        <ListItem Value="CA">California</ListItem>
+        <!-- ... more states ... -->
+    </DropDownList>
+
+    <ListSearchExtender
+        TargetControlID="ddlStates"
+        PromptText="Type state name..."
+        PromptPosition="PromptPosition.Top"
+        IsSorted="true"
+        QueryPattern="QueryPattern.StartsWith" />
+</div>
+
+

Search with Contains Pattern

+
@rendermode InteractiveServer
+
+<div>
+    <label>Find a Product:</label>
+
+    <ListBox ID="lstProducts" style="width: 250px; height: 200px;">
+        <ListItem>Widget Pro</ListItem>
+        <ListItem>Pro Widget</ListItem>
+        <ListItem>Super Widget</ListItem>
+        <ListItem>Widget Deluxe</ListItem>
+        <ListItem>Gadget Pro</ListItem>
+        <!-- ... more products ... -->
+    </ListBox>
+
+    <ListSearchExtender
+        TargetControlID="lstProducts"
+        PromptText="Search by product name..."
+        PromptPosition="PromptPosition.Top"
+        IsSorted="false"
+        QueryPattern="QueryPattern.Contains" />
+</div>
+
+

Search at Bottom

+
@rendermode InteractiveServer
+
+<div>
+    <label>Available Themes:</label>
+
+    <ListBox ID="lstThemes" style="width: 200px; height: 150px;">
+        <ListItem>Dark Modern</ListItem>
+        <ListItem>Light Classic</ListItem>
+        <ListItem>Blue Ocean</ListItem>
+        <ListItem>Forest Green</ListItem>
+        <ListItem>Sunset Orange</ListItem>
+    </ListBox>
+
+    <ListSearchExtender
+        TargetControlID="lstThemes"
+        PromptText="Filter themes..."
+        PromptPosition="PromptPosition.Bottom"
+        IsSorted="false"
+        QueryPattern="QueryPattern.Contains"
+        PromptCssClass="search-prompt" />
+</div>
+
+<style>
+    .search-prompt {
+        color: #999;
+        font-style: italic;
+        font-size: 12px;
+    }
+</style>
+
+

HTML Output

+

The ListSearchExtender creates a search input field positioned above or below the list control and filters the list items based on user input.

+

JavaScript Interop

+

The ListSearchExtender loads list-search-extender.js as an ES module. JavaScript handles:

+
    +
  • Creating and positioning the search input field
    • +
  • Listening to keyup events in the search field
    • +
  • Matching items against search text (Contains or StartsWith)
    • +
  • Showing/hiding list items based on matches
    • +
  • Auto-selecting first match if configured
    • +
  • Optimized binary search if list is sorted
    • +
  • Applying CSS classes to prompt
    • +
+

Render Mode Requirements

+

The ListSearchExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. List displays without search.
    • +
  • JavaScript disabled: Same as SSR — No search functionality.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:ListSearchExtender
++ <ListSearchExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use enum types for positions and patterns + 

    - PromptPosition="Top"
++ PromptPosition="PromptPosition.Top"
+- QueryPattern="StartsWith"
++ QueryPattern="QueryPattern.StartsWith"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:ListBox ID="lstCountries" runat="server" Height="150px">
+    <asp:ListItem>Afghanistan</asp:ListItem>
+    <asp:ListItem>Albania</asp:ListItem>
+    <!-- ... -->
+</asp:ListBox>
+
+<ajaxToolkit:ListSearchExtender
+    ID="search1"
+    TargetControlID="lstCountries"
+    PromptText="Search..."
+    IsSorted="true"
+    QueryPattern="StartsWith"
+    runat="server" />
+
+

After (Blazor)

+
<ListBox ID="lstCountries" style="height: 150px;">
+    <ListItem>Afghanistan</ListItem>
+    <ListItem>Albania</ListItem>
+    <!-- ... -->
+</ListBox>
+
+<ListSearchExtender
+    TargetControlID="lstCountries"
+    PromptText="Search..."
+    IsSorted="true"
+    QueryPattern="QueryPattern.StartsWith" />
+
+

Best Practices

+
    +
  1. Set IsSorted for large lists — If your list is sorted, enable IsSorted="true" for better performance
    2. +
  2. Choose QueryPattern wisely — Use StartsWith for name lists, Contains for flexible matching
    3. +
  3. Keep prompt text short — Use concise placeholder text (e.g., "Search..." vs "Type to search...")
    4. +
  4. Position search appropriately — Top is default and typically preferred
    5. +
  5. Test with many items — Verify performance with 100+ list items
    6. +
  6. Style the search — Use CSS to make the search input match your design
    7. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Search not appearingVerify TargetControlID matches the ListBox/DropDownList ID. Ensure @rendermode InteractiveServer is set.
Search not filteringVerify list items are being rendered. Check that IsSorted matches your actual list order.
Performance issues with large listsEnable IsSorted="true" if your list is sorted for optimized binary search.
StartsWith not working as expectedVerify items start with search text (case-sensitive). Try QueryPattern="QueryPattern.Contains".
Search prompt not visibleCheck CSS styling. Verify PromptPosition value is valid (Top or Bottom).
+

See Also

+
    +
  • Ajax Control Toolkit Overview — How extenders work and render mode requirements
    • +
  • ListBox Component — The ListBox control (documentation coming soon)
    • +
  • DropDownList Component — The DropDownList control (documentation coming soon)
    • +
  • Original Ajax Control Toolkit: https://www.asp.net/ajax/ajaxcontroltoolkit
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/MaskedEditExtender/index.html b/site/AjaxToolkit/MaskedEditExtender/index.html new file mode 100644 index 000000000..8ead34c20 --- /dev/null +++ b/site/AjaxToolkit/MaskedEditExtender/index.html @@ -0,0 +1,5458 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MaskedEditExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

MaskedEditExtender

+

The MaskedEditExtender applies an input mask to a target TextBox, restricting and formatting user input according to a mask pattern. It supports number, date, time, and custom masks with configurable prompt characters, input direction, and validation behavior.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/MaskedEditExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the TextBox to apply the mask to
    • +
  • Mask — The mask pattern string
    • +
  • MaskType — The type of mask (None, Number, Date, Time, DateTime)
    • +
  • InputDirection — Direction of text input (LeftToRight, RightToLeft)
    • +
  • PromptCharacter — Character displayed for unfilled mask positions
    • +
  • AutoComplete — Whether to enable browser autocomplete
    • +
  • AutoCompleteValue — Value to use for autocomplete
    • +
  • Filtered — Additional characters allowed beyond the mask definition
    • +
  • ClearMaskOnLostFocus — Remove mask characters when input loses focus
    • +
  • ClearTextOnInvalid — Clear text when it doesn't match the mask on blur
    • +
  • AcceptAMPM — Accept AM/PM designator for time masks
    • +
  • AcceptNegative — How negative values are displayed for number masks
    • +
  • ErrorTooltipEnabled — Show tooltip on validation failure
    • +
  • ErrorTooltipCssClass — CSS class for the error tooltip
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Mask Characters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CharacterDescription
9Digit (0–9)
LLetter (a–z, A–Z)
$Digit or space
CAny character
ALetter or digit
NDigit or letter (same as A)
?Any character (optional)
+

MaskType Enum

+
enum MaskType
+{
+    None = 0,      // Custom mask (default)
+    Number = 1,    // Numeric mask
+    Date = 2,      // Date mask
+    Time = 3,      // Time mask
+    DateTime = 4   // Date and time mask
+}
+
+

InputDirection Enum

+
enum InputDirection
+{
+    LeftToRight = 0,  // Standard left-to-right input (default)
+    RightToLeft = 1   // Right-to-left input (for currency, etc.)
+}
+
+

AcceptNegative Enum

+
enum AcceptNegative
+{
+    None = 0,   // No negative values allowed (default)
+    Left = 1,   // Negative sign on the left (e.g., -123)
+    Right = 2   // Negative sign on the right (e.g., 123-)
+}
+
+

Web Forms Syntax

+
<asp:TextBox ID="txtPhone" runat="server" />
+
+<ajaxToolkit:MaskedEditExtender
+    ID="mee1"
+    runat="server"
+    TargetControlID="txtPhone"
+    Mask="(999) 999-9999"
+    MaskType="None"
+    InputDirection="LeftToRight"
+    PromptCharacter="_"
+    ClearMaskOnLostFocus="true" />
+
+

Blazor Migration

+
<TextBox ID="txtPhone" />
+
+<MaskedEditExtender
+    TargetControlID="txtPhone"
+    Mask="(999) 999-9999"
+    MaskType="MaskType.None"
+    InputDirection="InputDirection.LeftToRight"
+    PromptCharacter="_"
+    ClearMaskOnLostFocus="true" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Use full enum type names for MaskType and InputDirection. Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the TextBox to apply the mask to
Maskstring""Mask pattern string (e.g., "999-999-9999" for phone)
MaskTypeMaskTypeNoneType of mask: None, Number, Date, Time, DateTime
InputDirectionInputDirectionLeftToRightDirection of text input: LeftToRight or RightToLeft
PromptCharacterstring"_"Character displayed for unfilled mask positions
AutoCompleteboolfalseWhether to enable browser autocomplete on the target input
AutoCompleteValuestring""Value to use for autocomplete when enabled
Filteredstring""Additional characters allowed beyond the mask definition
ClearMaskOnLostFocusbooltrueRemove mask characters when input loses focus
ClearTextOnInvalidboolfalseClear text when it doesn't match the mask on blur
AcceptAMPMboolfalseAccept AM/PM designator for time masks
AcceptNegativeAcceptNegativeNoneHow negative values are displayed: None, Left, Right
ErrorTooltipEnabledboolfalseShow tooltip with error info on validation failure
ErrorTooltipCssClassstring""CSS class applied to the error tooltip
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Phone Number Mask

+
@rendermode InteractiveServer
+
+<TextBox ID="txtPhone" />
+
+<MaskedEditExtender
+    TargetControlID="txtPhone"
+    Mask="(999) 999-9999"
+    ClearMaskOnLostFocus="true" />
+
+

Date Mask

+
@rendermode InteractiveServer
+
+<TextBox ID="txtDate" />
+
+<MaskedEditExtender
+    TargetControlID="txtDate"
+    Mask="99/99/9999"
+    MaskType="MaskType.Date"
+    ClearMaskOnLostFocus="false" />
+
+

Currency Mask with Negative Support

+
@rendermode InteractiveServer
+
+<TextBox ID="txtAmount" />
+
+<MaskedEditExtender
+    TargetControlID="txtAmount"
+    Mask="999,999.99"
+    MaskType="MaskType.Number"
+    InputDirection="InputDirection.RightToLeft"
+    AcceptNegative="AcceptNegative.Left" />
+
+

Time Mask with AM/PM

+
@rendermode InteractiveServer
+
+<TextBox ID="txtTime" />
+
+<MaskedEditExtender
+    TargetControlID="txtTime"
+    Mask="99:99"
+    MaskType="MaskType.Time"
+    AcceptAMPM="true" />
+
+

Social Security Number Mask

+
@rendermode InteractiveServer
+
+<TextBox ID="txtSSN" />
+
+<MaskedEditExtender
+    TargetControlID="txtSSN"
+    Mask="999-99-9999"
+    PromptCharacter="#"
+    ClearMaskOnLostFocus="true"
+    ClearTextOnInvalid="true"
+    ErrorTooltipEnabled="true" />
+
+

HTML Output

+

The MaskedEditExtender produces no HTML itself — it attaches JavaScript behavior to the target TextBox that intercepts keystrokes and enforces the mask pattern.

+

JavaScript Interop

+

The MaskedEditExtender loads masked-edit-extender.js as an ES module. JavaScript handles:

+
    +
  • Intercepting keystrokes and enforcing mask patterns
    • +
  • Positioning the cursor within the mask
    • +
  • Handling paste operations (stripping invalid characters)
    • +
  • Displaying prompt characters for unfilled positions
    • +
  • Clearing/showing the mask on focus/blur
    • +
  • Error tooltip display on validation failure
    • +
+

Render Mode Requirements

+

The MaskedEditExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The TextBox works as a plain text input without masking.
    • +
  • JavaScript disabled: Same as SSR — TextBox functions without mask enforcement.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:MaskedEditExtender
++ <MaskedEditExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use full enum type names + 

    - MaskType="Number"
++ MaskType="MaskType.Number"
+- InputDirection="RightToLeft"
++ InputDirection="InputDirection.RightToLeft"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtPhone" runat="server" />
+
+<ajaxToolkit:MaskedEditExtender
+    ID="mee1"
+    TargetControlID="txtPhone"
+    Mask="(999) 999-9999"
+    ClearMaskOnLostFocus="true"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtPhone" />
+
+<MaskedEditExtender
+    TargetControlID="txtPhone"
+    Mask="(999) 999-9999"
+    ClearMaskOnLostFocus="true" />
+
+

Best Practices

+
    +
  1. Choose the right MaskType — Use Number, Date, or Time for built-in validation
    2. +
  2. Set ClearMaskOnLostFocus wisely — true shows clean values; false shows the mask structure
    3. +
  3. Use ClearTextOnInvalid — Prevents partial entries from being submitted
    4. +
  4. Pair with validators — Combine with RequiredFieldValidator or CustomValidator for server-side validation
    5. +
  5. Test with paste — Ensure pasted values are properly filtered
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Mask not appearingVerify TargetControlID matches the TextBox's ID. Ensure @rendermode InteractiveServer is set.
Wrong characters acceptedCheck Mask pattern uses correct mask characters (9, L, $, C, A).
Cursor jumping unexpectedlyVerify InputDirection matches your intended input flow.
Negative values not acceptedSet AcceptNegative to Left or Right and ensure MaskType is Number.
Error tooltip not showingSet ErrorTooltipEnabled="true" and optionally provide ErrorTooltipCssClass.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/ModalPopupExtender/index.html b/site/AjaxToolkit/ModalPopupExtender/index.html new file mode 100644 index 000000000..0353e89c0 --- /dev/null +++ b/site/AjaxToolkit/ModalPopupExtender/index.html @@ -0,0 +1,5572 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ModalPopupExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ModalPopupExtender

+

The ModalPopupExtender displays a target element as a modal popup dialog with an overlay backdrop. It supports OK/Cancel button actions, focus trapping, optional drag behavior, and Escape key dismissal, enabling modal interactions with minimal markup.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/ModalPopupExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the control that triggers the modal display
    • +
  • PopupControlID — ID of the element to display as the modal popup
    • +
  • BackgroundCssClass — CSS class applied to the overlay backdrop
    • +
  • OkControlID — ID of the button that confirms and closes the modal
    • +
  • CancelControlID — ID of the button that cancels and closes the modal
    • +
  • OnOkScript — JavaScript code to execute when OK is clicked
    • +
  • OnCancelScript — JavaScript code to execute when Cancel is clicked or Escape is pressed
    • +
  • DropShadow — Whether to add a drop shadow effect to the popup
    • +
  • Drag — Whether the popup can be dragged by the user
    • +
  • PopupDragHandleControlID — ID of the element to use as a drag handle (optional)
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Syntax

+
<asp:Button ID="btnOpenModal" Text="Open Settings" runat="server" />
+
+<div ID="modalSettings" style="display: none; width: 400px; background: white; padding: 20px;">
+    <h2>Settings</h2>
+    <p>This is the modal content.</p>
+
+    <button ID="btnOK">OK</button>
+    <button ID="btnCancel">Cancel</button>
+</div>
+
+<ajaxToolkit:ModalPopupExtender 
+    ID="mpe"
+    runat="server"
+    TargetControlID="btnOpenModal"
+    PopupControlID="modalSettings"
+    BackgroundCssClass="modalBackground"
+    OkControlID="btnOK"
+    CancelControlID="btnCancel"
+    DropShadow="true"
+    Drag="true" />
+
+

Blazor Migration

+
<Button ID="btnOpenModal" Text="Open Settings" />
+
+<div ID="modalSettings" style="display: none; width: 400px; background: white; padding: 20px;">
+    <h2>Settings</h2>
+    <p>This is the modal content.</p>
+
+    <button ID="btnOK">OK</button>
+    <button ID="btnCancel">Cancel</button>
+</div>
+
+<ModalPopupExtender 
+    TargetControlID="btnOpenModal"
+    PopupControlID="modalSettings"
+    BackgroundCssClass="modalBackground"
+    OkControlID="btnOK"
+    CancelControlID="btnCancel"
+    DropShadow="true"
+    Drag="true" />
+
+

Migration is simple: Just remove the ajaxToolkit: prefix and remove the runat="server" and ID attributes. Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the control that opens the modal when clicked
PopupControlIDstring(required)ID of the element to display as the modal popup
BackgroundCssClassstring""CSS class applied to the overlay backdrop
OkControlIDstring""ID of the button that confirms and closes the modal
CancelControlIDstring""ID of the button that cancels and closes the modal
OnOkScriptstring""JavaScript code to execute when OK button is clicked
OnCancelScriptstring""JavaScript code to execute when Cancel button is clicked or Escape key is pressed
DropShadowboolfalseWhether to add a drop shadow effect to the popup
DragboolfalseWhether the popup can be dragged by the user
PopupDragHandleControlIDstring""ID of the element to use as a drag handle; if empty, entire popup is draggable
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Modal Confirmation

+
@rendermode InteractiveServer
+
+<Button ID="btnDelete" Text="Delete" />
+
+<div ID="confirmDialog" style="display: none; width: 350px; background: white; padding: 20px; border-radius: 8px;">
+    <h3>Confirm Action</h3>
+    <p>Are you sure you want to delete this item?</p>
+    <button ID="btnConfirm" style="padding: 8px 16px; margin-right: 10px;">Yes, Delete</button>
+    <button ID="btnDismiss" style="padding: 8px 16px;">Cancel</button>
+</div>
+
+<ModalPopupExtender 
+    TargetControlID="btnDelete"
+    PopupControlID="confirmDialog"
+    OkControlID="btnConfirm"
+    CancelControlID="btnDismiss"
+    BackgroundCssClass="backdrop" />
+
+<style>
+    .backdrop {
+        background-color: rgba(0, 0, 0, 0.5);
+    }
+</style>
+
+ +
@rendermode InteractiveServer
+
+<Button ID="btnSettings" Text="Open Settings" />
+
+<div ID="settingsDialog" style="display: none; width: 400px; background: white; padding: 0; border-radius: 8px; overflow: hidden;">
+    <div ID="dragHandle" style="background: #333; color: white; padding: 15px; cursor: move;">
+        Settings
+    </div>
+
+    <div style="padding: 20px;">
+        <label>
+            Option 1:
+            <input type="checkbox" @bind-checked="@option1" />
+        </label>
+        <br />
+        <label>
+            Option 2:
+            <input type="checkbox" @bind-checked="@option2" />
+        </label>
+    </div>
+
+    <div style="padding: 20px; border-top: 1px solid #eee; display: flex; gap: 10px; justify-content: flex-end;">
+        <button ID="btnSave" style="padding: 8px 16px; background: #007bff; color: white; border: none; cursor: pointer; border-radius: 4px;">Save</button>
+        <button ID="btnCancel" style="padding: 8px 16px; background: #6c757d; color: white; border: none; cursor: pointer; border-radius: 4px;">Cancel</button>
+    </div>
+</div>
+
+<ModalPopupExtender 
+    TargetControlID="btnSettings"
+    PopupControlID="settingsDialog"
+    OkControlID="btnSave"
+    CancelControlID="btnCancel"
+    BackgroundCssClass="modal-backdrop"
+    DropShadow="true"
+    Drag="true"
+    PopupDragHandleControlID="dragHandle" />
+
+<style>
+    .modal-backdrop {
+        background-color: rgba(0, 0, 0, 0.6);
+    }
+</style>
+
+@code {
+    private bool option1 = false;
+    private bool option2 = false;
+}
+
+ +
@rendermode InteractiveServer
+
+<Button ID="btnAction" Text="Perform Action" />
+
+<div ID="actionModal" style="display: none; width: 400px; background: white; padding: 20px; border-radius: 8px;">
+    <h3>Perform Action</h3>
+    <p>This action will process the selected items.</p>
+
+    <button ID="btnProceed" style="padding: 8px 16px; margin-right: 10px;">Proceed</button>
+    <button ID="btnCancel" style="padding: 8px 16px;">Cancel</button>
+</div>
+
+<ModalPopupExtender 
+    TargetControlID="btnAction"
+    PopupControlID="actionModal"
+    OkControlID="btnProceed"
+    CancelControlID="btnCancel"
+    BackgroundCssClass="backdrop"
+    OnOkScript="onModalOK()"
+    OnCancelScript="onModalCancel()" />
+
+<script>
+    function onModalOK() {
+        console.log('User confirmed action');
+    }
+
+    function onModalCancel() {
+        console.log('User cancelled action');
+    }
+</script>
+
+<style>
+    .backdrop {
+        background-color: rgba(0, 0, 0, 0.5);
+    }
+</style>
+
+ +
@rendermode InteractiveServer
+
+<Button ID="btnAddItem" Text="Add New Item" />
+
+<div ID="formDialog" style="display: none; width: 450px; background: white; padding: 30px; border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);">
+    <h3>Add New Item</h3>
+
+    <div style="margin: 15px 0;">
+        <label for="itemName">Item Name:</label>
+        <input type="text" ID="itemName" @bind-value="@itemName" style="width: 100%; padding: 8px; margin-top: 5px; border: 1px solid #ddd; border-radius: 4px;" />
+    </div>
+
+    <div style="margin: 15px 0;">
+        <label for="itemCategory">Category:</label>
+        <select ID="itemCategory" @bind="@itemCategory" style="width: 100%; padding: 8px; margin-top: 5px; border: 1px solid #ddd; border-radius: 4px;">
+            <option value="">Select...</option>
+            <option value="electronics">Electronics</option>
+            <option value="clothing">Clothing</option>
+            <option value="other">Other</option>
+        </select>
+    </div>
+
+    <div style="margin-top: 25px; display: flex; gap: 10px; justify-content: flex-end;">
+        <button ID="btnAdd" style="padding: 10px 20px; background: #28a745; color: white; border: none; cursor: pointer; border-radius: 4px;">Add</button>
+        <button ID="btnClose" style="padding: 10px 20px; background: #6c757d; color: white; border: none; cursor: pointer; border-radius: 4px;">Close</button>
+    </div>
+</div>
+
+<ModalPopupExtender 
+    TargetControlID="btnAddItem"
+    PopupControlID="formDialog"
+    OkControlID="btnAdd"
+    CancelControlID="btnClose"
+    BackgroundCssClass="form-modal-backdrop"
+    DropShadow="true" />
+
+<style>
+    .form-modal-backdrop {
+        background-color: rgba(0, 0, 0, 0.6);
+        z-index: 999;
+    }
+</style>
+
+@code {
+    private string itemName = "";
+    private string itemCategory = "";
+}
+
+

HTML Output

+

The ModalPopupExtender produces no HTML itself — it only attaches JavaScript behavior to the popup element.

+

Before (initial state): +

<button id="btnDelete">Delete</button>
+
+<div id="confirmDialog" style="display: none; width: 350px;">
+    <!-- Dialog content -->
+</div>
+

+

When button is clicked: +1. Overlay backdrop is created and inserted +2. Modal popup is shown (display changes from none to block) +3. Modal receives focus +4. Backdrop covers the page behind the modal

+

On OK or Cancel: +- Modal and backdrop are hidden or removed +- Focus returns to the trigger button +- Associated callback script executes (if provided)

+ +

Opening the Modal

+
    +
  • Clicking the target control (e.g., button) opens the modal
    • +
  • An overlay backdrop appears behind the modal
    • +
  • The modal receives keyboard focus
    • +
  • Escape key closes the modal (executes OnCancelScript)
    • +
+ +
    +
  • Modal is centered on the page
    • +
  • Backdrop covers the entire viewport
    • +
  • User cannot interact with page elements behind the modal
    • +
+

Closing the Modal

+
    +
  • OK button: Executes OnOkScript, then closes modal
    • +
  • Cancel button: Executes OnCancelScript, then closes modal
    • +
  • Escape key: Executes OnCancelScript, then closes modal
    • +
+

Drag Support

+

When Drag="true": +- Entire modal can be dragged by the user by default +- If PopupDragHandleControlID is set, only that element serves as the drag handle +- Dragging moves the modal within the viewport

+

Styling Notes

+
    +
  • The backdrop is created as a <div> with position: fixed; top: 0; left: 0
    • +
  • Apply your CSS class to the BackgroundCssClass property to customize overlay appearance
    • +
  • Use opacity, background-color, or backdrop-filter CSS properties for visual effects
    • +
  • The modal itself retains the styling you define in your markup
    • +
+

Render Mode Requirements

+

The ModalPopupExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+<Button ID="btnOpen" Text="Open" />
+<div ID="popup">Modal content</div>
+<ModalPopupExtender TargetControlID="btnOpen" PopupControlID="popup" />
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The modal element remains hidden and the target button doesn't open it.
    • +
  • JavaScript disabled: Same as SSR — modal doesn't function (element stays hidden).
    • +
  • Module import fails: Any JavaScript errors are logged to browser console; button continues to function but modal doesn't open.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:ModalPopupExtender
++ <ModalPopupExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes + 

    - runat="server"
+- ID="mpe"
+

    +
    3. +
  3. +

    Keep all properties the same + 

    TargetControlID="btnOpen"
+PopupControlID="myModal"
+OkControlID="btnOK"
+CancelControlID="btnCancel"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Button ID="btnOpen" Text="Open" runat="server" />
+
+<div ID="myModal" style="display: none; background: white; padding: 20px;">
+    <p>Modal content</p>
+    <button ID="btnOK">OK</button>
+    <button ID="btnCancel">Cancel</button>
+</div>
+
+<ajaxToolkit:ModalPopupExtender 
+    ID="mpe"
+    TargetControlID="btnOpen"
+    PopupControlID="myModal"
+    OkControlID="btnOK"
+    CancelControlID="btnCancel"
+    BackgroundCssClass="modalBackground"
+    runat="server" />
+
+

After (Blazor)

+
<Button ID="btnOpen" Text="Open" />
+
+<div ID="myModal" style="display: none; background: white; padding: 20px;">
+    <p>Modal content</p>
+    <button ID="btnOK">OK</button>
+    <button ID="btnCancel">Cancel</button>
+</div>
+
+<ModalPopupExtender 
+    TargetControlID="btnOpen"
+    PopupControlID="myModal"
+    OkControlID="btnOK"
+    CancelControlID="btnCancel"
+    BackgroundCssClass="modalBackground" />
+
+

Best Practices

+
    +
  1. Use semantic HTML inside modals — Structure with <h3>, <p>, proper labels for inputs
    2. +
  2. Provide visual feedback — Use distinct colors for OK/Cancel buttons (green/blue vs. gray)
    3. +
  3. Center content — Use flexbox or grid on the modal container for readable layouts
    4. +
  4. Handle Escape key — Always implement OnCancelScript to match browser expectations
    5. +
  5. Set a reasonable width — 350–500px is typical; avoid full-screen modals
    6. +
  6. Test drag behavior — If dragging is enabled, ensure header is clearly draggable
    7. +
  7. Minimize content — Users prefer quick decisions; keep modal content focused
    8. +
  8. Accessibility: Use proper <label> elements for form inputs inside modals
    9. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Modal not openingVerify TargetControlID matches button's ID. Ensure @rendermode InteractiveServer is set. Check browser console for JavaScript errors.
Modal always visibleVerify popup element has style="display: none;" or display: none; CSS. Modal should be hidden initially.
Can't close modalVerify OkControlID and CancelControlID button IDs match their ID attributes. Ensure buttons are inside the modal container.
Backdrop not styledVerify BackgroundCssClass is defined in your CSS. Check CSS class name spelling (case-sensitive).
Drag not workingVerify Drag="true" is set. If using PopupDragHandleControlID, ensure the ID matches exactly. Try without drag handle first to test.
Multiple modals open at onceAvoid triggering multiple ModalPopupExtenders simultaneously. Use a queue or state management to control which modal is visible.
Modal behind other elementsCheck CSS z-index values. Backdrop and modal should have high z-index values (999+).
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/NumericUpDownExtender/index.html b/site/AjaxToolkit/NumericUpDownExtender/index.html new file mode 100644 index 000000000..3fa6cdaca --- /dev/null +++ b/site/AjaxToolkit/NumericUpDownExtender/index.html @@ -0,0 +1,5247 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + NumericUpDownExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

NumericUpDownExtender

+

The NumericUpDownExtender adds numeric up/down spinner buttons to a target TextBox. Users can increment or decrement the value using the spinner buttons or by typing directly. It supports min/max range constraints, configurable step increments, and cycling through a reference value list.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/NumericUpDownExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the TextBox to enhance with spinner buttons
    • +
  • Width — Width of the spinner control in pixels
    • +
  • Minimum — The minimum allowed value
    • +
  • Maximum — The maximum allowed value
    • +
  • Step — Amount to increment/decrement on each step
    • +
  • RefValues — Semicolon-separated list of values to cycle through
    • +
  • ServiceUpPath — URL of the web service for the up action
    • +
  • ServiceUpMethod — Web service method name for the up action
    • +
  • ServiceDownPath — URL of the web service for the down action
    • +
  • ServiceDownMethod — Web service method name for the down action
    • +
  • Tag — Arbitrary string passed to the web service methods
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Syntax

+
<asp:TextBox ID="txtQuantity" Text="1" runat="server" />
+
+<ajaxToolkit:NumericUpDownExtender
+    ID="nud1"
+    runat="server"
+    TargetControlID="txtQuantity"
+    Width="120"
+    Minimum="1"
+    Maximum="100"
+    Step="1" />
+
+

Blazor Migration

+
<TextBox ID="txtQuantity" Text="1" />
+
+<NumericUpDownExtender
+    TargetControlID="txtQuantity"
+    Width="120"
+    Minimum="1"
+    Maximum="100"
+    Step="1" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the TextBox to enhance with spinner buttons
Widthint100Width of the spinner control in pixels
Minimumdoubledouble.MinValueThe minimum allowed value
Maximumdoubledouble.MaxValueThe maximum allowed value
Stepdouble1Amount to increment or decrement on each step
RefValuesstring""Semicolon-separated list of values to cycle through instead of numeric stepping
ServiceUpPathstring""URL of the web service for the up action
ServiceUpMethodstring""Web service method name for the up action
ServiceDownPathstring""URL of the web service for the down action
ServiceDownMethodstring""Web service method name for the down action
Tagstring""Arbitrary string passed to the web service methods
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Numeric Spinner

+
@rendermode InteractiveServer
+
+<TextBox ID="txtQty" Text="1" />
+
+<NumericUpDownExtender
+    TargetControlID="txtQty"
+    Minimum="0"
+    Maximum="99"
+    Step="1" />
+
+

Decimal Step Spinner

+
@rendermode InteractiveServer
+
+<TextBox ID="txtPrice" Text="0.00" />
+
+<NumericUpDownExtender
+    TargetControlID="txtPrice"
+    Minimum="0"
+    Maximum="999.99"
+    Step="0.50"
+    Width="150" />
+
+

Cycling Through Reference Values

+

Instead of numeric stepping, cycle through a list of predefined values:

+
@rendermode InteractiveServer
+
+<TextBox ID="txtMonth" Text="January" />
+
+<NumericUpDownExtender
+    TargetControlID="txtMonth"
+    RefValues="January;February;March;April;May;June;July;August;September;October;November;December"
+    Width="150" />
+
+

Spinner with Custom Width

+
@rendermode InteractiveServer
+
+<label>Quantity:</label>
+<TextBox ID="txtOrderQty" Text="1" />
+
+<NumericUpDownExtender
+    TargetControlID="txtOrderQty"
+    Minimum="1"
+    Maximum="50"
+    Step="1"
+    Width="80" />
+
+

HTML Output

+

The NumericUpDownExtender produces no HTML itself — it attaches JavaScript behavior to the target TextBox, adding spinner buttons and keyboard increment/decrement support.

+

JavaScript Interop

+

The NumericUpDownExtender loads numeric-updown-extender.js as an ES module. JavaScript handles:

+
    +
  • Rendering up/down spinner buttons adjacent to the TextBox
    • +
  • Incrementing/decrementing the value on button click
    • +
  • Enforcing min/max range constraints
    • +
  • Cycling through reference values when RefValues is set
    • +
  • Optional web service calls for custom up/down logic
    • +
+

Render Mode Requirements

+

The NumericUpDownExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The TextBox works as a plain text input.
    • +
  • JavaScript disabled: Same as SSR — TextBox functions without spinner buttons.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:NumericUpDownExtender
++ <NumericUpDownExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Update service paths if using web service integration + 

    - ServiceUpPath="~/Services/Counter.asmx"
++ ServiceUpPath="/api/counter"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtQty" Text="1" runat="server" />
+
+<ajaxToolkit:NumericUpDownExtender
+    ID="nud1"
+    TargetControlID="txtQty"
+    Minimum="1"
+    Maximum="100"
+    Step="1"
+    Width="120"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtQty" Text="1" />
+
+<NumericUpDownExtender
+    TargetControlID="txtQty"
+    Minimum="1"
+    Maximum="100"
+    Step="1"
+    Width="120" />
+
+

Best Practices

+
    +
  1. Set sensible min/max — Prevent out-of-range values
    2. +
  2. Choose an appropriate step — Match the precision your field requires
    3. +
  3. Use RefValues for non-numeric data — Months, sizes, priorities, etc.
    4. +
  4. Set Width to match — Ensure the TextBox is wide enough for the value plus spinner buttons
    5. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Spinner not appearingVerify TargetControlID matches the TextBox's ID. Ensure @rendermode InteractiveServer is set.
Value exceeds rangeVerify Minimum and Maximum are set correctly.
RefValues not cyclingEnsure values are separated by semicolons (;).
Decimal stepping inaccurateUse appropriate Step values (e.g., 0.01, 0.1, 0.5).
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/PasswordStrength/index.html b/site/AjaxToolkit/PasswordStrength/index.html new file mode 100644 index 000000000..02fadb1d6 --- /dev/null +++ b/site/AjaxToolkit/PasswordStrength/index.html @@ -0,0 +1,5399 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + PasswordStrength - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

PasswordStrength

+

The PasswordStrength extender displays a visual indicator of password strength as the user types in a password field. It evaluates passwords against configurable character requirements (length, uppercase, lowercase, numbers, symbols) and displays feedback through text labels or a visual bar indicator.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/PasswordStrength

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the password TextBox to monitor
    • +
  • DisplayPosition — Where to show the strength indicator (RightSide, LeftSide, AboveRight, AboveLeft, BelowRight, BelowLeft)
    • +
  • StrengthIndicatorType — Text labels or BarIndicator display
    • +
  • PreferredPasswordLength — Target minimum length
    • +
  • MinimumNumericCharacters — Required numeric characters
    • +
  • MinimumSymbolCharacters — Required symbol characters
    • +
  • MinimumUpperCaseCharacters — Required uppercase letters
    • +
  • MinimumLowerCaseCharacters — Required lowercase letters
    • +
  • RequiresUpperAndLowerCaseCharacters — Must contain both upper and lower
    • +
  • TextStrengthDescriptions — Semicolon-delimited strength labels
    • +
  • StrengthStyles — CSS classes for each strength level
    • +
  • BarBorderCssClass — CSS class for bar indicator border
    • +
  • TextCssClass — CSS class for text display
    • +
  • HelpHandleCssClass — CSS class for help icon
    • +
  • HelpHandlePosition — Where to show the help handle
    • +
+

DisplayPosition Enum

+

Controls where the indicator displays:

+
enum DisplayPosition
+{
+    RightSide = 0,
+    LeftSide = 1,
+    AboveRight = 2,
+    AboveLeft = 3,
+    BelowRight = 4,
+    BelowLeft = 5
+}
+
+

StrengthIndicatorType Enum

+

Controls the display style:

+
enum StrengthIndicatorType
+{
+    Text = 0,        // Text labels
+    BarIndicator = 1 // Visual progress bar
+}
+
+

Web Forms Syntax

+
<asp:TextBox ID="txtPassword" runat="server" TextMode="Password" />
+
+<ajaxToolkit:PasswordStrength
+    ID="pwd1"
+    runat="server"
+    TargetControlID="txtPassword"
+    DisplayPosition="RightSide"
+    StrengthIndicatorType="BarIndicator"
+    PreferredPasswordLength="10"
+    MinimumNumericCharacters="1"
+    MinimumSymbolCharacters="1"
+    MinimumUpperCaseCharacters="1"
+    TextStrengthDescriptions="Very Poor;Weak;Average;Strong;Excellent" />
+
+

Blazor Migration

+
<TextBox ID="txtPassword" type="password" />
+
+<PasswordStrength
+    TargetControlID="txtPassword"
+    DisplayPosition="DisplayPosition.RightSide"
+    StrengthIndicatorType="StrengthIndicatorType.BarIndicator"
+    PreferredPasswordLength="10"
+    MinimumNumericCharacters="1"
+    MinimumSymbolCharacters="1"
+    MinimumUpperCaseCharacters="1"
+    TextStrengthDescriptions="Very Poor;Weak;Average;Strong;Excellent" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Use enum type names for positions and indicator types!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the password TextBox to monitor
DisplayPositionDisplayPositionRightSideWhere to display the strength indicator
StrengthIndicatorTypeStrengthIndicatorTypeTextText labels or BarIndicator display
PreferredPasswordLengthint10Target minimum password length
MinimumNumericCharactersint0Minimum required numeric characters (0-9)
MinimumSymbolCharactersint0Minimum required symbol characters
MinimumUpperCaseCharactersint0Minimum required uppercase letters
MinimumLowerCaseCharactersint0Minimum required lowercase letters
RequiresUpperAndLowerCaseCharactersboolfalseMust contain both uppercase and lowercase
TextStrengthDescriptionsstring""Semicolon-delimited strength labels (e.g., "Very Poor;Weak;Average;Strong;Excellent")
StrengthStylesstring""Semicolon-delimited CSS classes, one per strength level
BarBorderCssClassstring""CSS class for bar indicator border
TextCssClassstring""CSS class for text display element
HelpHandleCssClassstring""CSS class for help icon
HelpHandlePositionDisplayPositionRightSideWhere to display the help handle
+

Usage Examples

+

Basic Password Strength with Text

+
@rendermode InteractiveServer
+
+<div>
+    <label>Password:</label>
+    <TextBox ID="txtPass" type="password" style="width: 200px;" />
+
+    <PasswordStrength
+        TargetControlID="txtPass"
+        DisplayPosition="DisplayPosition.RightSide"
+        StrengthIndicatorType="StrengthIndicatorType.Text"
+        PreferredPasswordLength="8"
+        MinimumNumericCharacters="1"
+        TextStrengthDescriptions="Very Weak;Weak;Good;Strong;Very Strong" />
+</div>
+
+

Password Strength with Bar Indicator

+
@rendermode InteractiveServer
+
+<div>
+    <label>New Password:</label>
+    <TextBox ID="txtNewPassword" type="password" style="width: 250px;" />
+
+    <PasswordStrength
+        TargetControlID="txtNewPassword"
+        DisplayPosition="DisplayPosition.BelowRight"
+        StrengthIndicatorType="StrengthIndicatorType.BarIndicator"
+        PreferredPasswordLength="12"
+        MinimumNumericCharacters="1"
+        MinimumSymbolCharacters="1"
+        MinimumUpperCaseCharacters="1"
+        MinimumLowerCaseCharacters="1"
+        BarBorderCssClass="strength-bar-border"
+        StrengthStyles="very-weak;weak;fair;good;excellent" />
+</div>
+
+<style>
+    .strength-bar-border {
+        border: 1px solid #ccc;
+        height: 20px;
+        margin-top: 5px;
+        border-radius: 3px;
+    }
+
+    .very-weak { background-color: #d32f2f; }
+    .weak { background-color: #f57c00; }
+    .fair { background-color: #fbc02d; }
+    .good { background-color: #689f38; }
+    .excellent { background-color: #00796b; }
+</style>
+
+

Strict Password Requirements

+
@rendermode InteractiveServer
+
+<form>
+    <div style="margin-bottom: 20px;">
+        <label>Create Password (minimum 14 characters, mixed case, numbers, and symbols):</label>
+        <TextBox ID="txtStrictPass" type="password" style="width: 300px;" />
+
+        <PasswordStrength
+            TargetControlID="txtStrictPass"
+            DisplayPosition="DisplayPosition.BelowRight"
+            StrengthIndicatorType="StrengthIndicatorType.BarIndicator"
+            PreferredPasswordLength="14"
+            MinimumNumericCharacters="2"
+            MinimumSymbolCharacters="2"
+            MinimumUpperCaseCharacters="1"
+            MinimumLowerCaseCharacters="1"
+            RequiresUpperAndLowerCaseCharacters="true"
+            TextStrengthDescriptions="Insufficient;Weak;Fair;Good;Strong;Very Strong"
+            StrengthStyles="strength-0;strength-1;strength-2;strength-3;strength-4;strength-5" />
+    </div>
+
+    <button type="submit" class="btn btn-primary">Register</button>
+</form>
+
+<style>
+    .strength-0 { background-color: #d32f2f; width: 0%; }
+    .strength-1 { background-color: #f57c00; width: 20%; }
+    .strength-2 { background-color: #fbc02d; width: 40%; }
+    .strength-3 { background-color: #abb52e; width: 60%; }
+    .strength-4 { background-color: #7cb342; width: 80%; }
+    .strength-5 { background-color: #00796b; width: 100%; }
+</style>
+
+

Relaxed Password Requirements

+
@rendermode InteractiveServer
+
+<TextBox ID="txtSimple" type="password" style="width: 200px;" />
+
+<PasswordStrength
+    TargetControlID="txtSimple"
+    DisplayPosition="DisplayPosition.RightSide"
+    StrengthIndicatorType="StrengthIndicatorType.Text"
+    PreferredPasswordLength="6"
+    TextStrengthDescriptions="Too Short;Weak;Fair;Good;Strong"
+    TextCssClass="strength-label" />
+
+<style>
+    .strength-label {
+        font-weight: bold;
+        margin-left: 10px;
+    }
+</style>
+
+

HTML Output

+

The PasswordStrength extender produces a strength indicator element (typically a <div>) positioned near the password field, displaying either text labels or a visual bar.

+

JavaScript Interop

+

The PasswordStrength loads password-strength.js as an ES module. JavaScript handles:

+
    +
  • Monitoring password field input events
    • +
  • Evaluating password against character requirements
    • +
  • Calculating strength score based on weights
    • +
  • Updating indicator display in real-time
    • +
  • Managing text label visibility and styling
    • +
  • Updating bar indicator width
    • +
  • Positioning indicator relative to the password field
    • +
+

Render Mode Requirements

+

The PasswordStrength requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. Password field works normally without feedback.
    • +
  • JavaScript disabled: Same as SSR — No strength indicator appears.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:PasswordStrength
++ <PasswordStrength
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use enum types for positions and indicator types + 

    - DisplayPosition="RightSide"
++ DisplayPosition="DisplayPosition.RightSide"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtPassword" runat="server" TextMode="Password" />
+
+<ajaxToolkit:PasswordStrength
+    ID="pwd1"
+    TargetControlID="txtPassword"
+    DisplayPosition="RightSide"
+    StrengthIndicatorType="BarIndicator"
+    PreferredPasswordLength="8"
+    MinimumNumericCharacters="1"
+    TextStrengthDescriptions="Weak;Fair;Good;Strong"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtPassword" type="password" />
+
+<PasswordStrength
+    TargetControlID="txtPassword"
+    DisplayPosition="DisplayPosition.RightSide"
+    StrengthIndicatorType="StrengthIndicatorType.BarIndicator"
+    PreferredPasswordLength="8"
+    MinimumNumericCharacters="1"
+    TextStrengthDescriptions="Weak;Fair;Good;Strong" />
+
+

Best Practices

+
    +
  1. Balance security with usability — Don't require overly strict passwords that frustrate users
    2. +
  2. Show requirements upfront — Consider displaying password requirements above the field
    3. +
  3. Use BarIndicator for visual feedback — Bars are more intuitive than text for strength
    4. +
  4. Provide clear descriptions — Use labels like "Strong" vs "Very Strong" that users understand
    5. +
  5. Position wisely — Place indicator where it won't obscure other form fields
    6. +
  6. Test requirements — Verify your character rules are achievable and reasonable
    7. +
  7. Combine with validation — Use server-side validation in addition to client feedback
    8. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Indicator not appearingVerify TargetControlID matches the TextBox's ID. Ensure @rendermode InteractiveServer is set.
Bar indicator not fillingDefine StrengthStyles with CSS classes and ensure corresponding styles are in your stylesheet.
Descriptions not showingIf using StrengthIndicatorType.Text, provide TextStrengthDescriptions separated by semicolons.
Requirements too strictAdjust PreferredPasswordLength and character requirements to match your security policy.
Indicator in wrong positionUse a different DisplayPosition value. Try AboveRight, BelowRight, or LeftSide.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/PopupControlExtender/index.html b/site/AjaxToolkit/PopupControlExtender/index.html new file mode 100644 index 000000000..34c1d9da3 --- /dev/null +++ b/site/AjaxToolkit/PopupControlExtender/index.html @@ -0,0 +1,5265 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + PopupControlExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

PopupControlExtender

+

The PopupControlExtender attaches a popup panel to a target control, displaying it when the target is clicked. It is lighter than the ModalPopupExtender — no overlay backdrop, no focus trap. The popup supports positional placement, commit property/script support, and outside-click dismissal.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/PopupControlExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the control that triggers the popup on click
    • +
  • PopupControlID — ID of the panel element to display as a popup
    • +
  • Position — Position of the popup relative to the target control
    • +
  • OffsetX — Horizontal offset in pixels from the calculated position
    • +
  • OffsetY — Vertical offset in pixels from the calculated position
    • +
  • CommitProperty — Property on the target control to set when popup is committed
    • +
  • CommitScript — JavaScript to execute when the popup is committed
    • +
  • ExtenderControlID — ID for programmatic access to the extender
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

PopupPosition Enum

+
enum PopupPosition
+{
+    Left = 0,     // To the left of target
+    Right = 1,    // To the right of target
+    Top = 2,      // Above target
+    Bottom = 3,   // Below target (default)
+    Center = 4    // Centered on target
+}
+
+

Web Forms Syntax

+
<asp:TextBox ID="txtColor" runat="server" />
+
+<asp:Panel ID="pnlColorPicker" runat="server" style="display: none;">
+    <div class="color-grid">
+        <span style="background: red;" onclick="commitColor('red')"></span>
+        <span style="background: blue;" onclick="commitColor('blue')"></span>
+        <span style="background: green;" onclick="commitColor('green')"></span>
+    </div>
+</asp:Panel>
+
+<ajaxToolkit:PopupControlExtender
+    ID="pce1"
+    runat="server"
+    TargetControlID="txtColor"
+    PopupControlID="pnlColorPicker"
+    Position="Bottom"
+    CommitProperty="value"
+    CommitScript="onColorCommit()" />
+
+

Blazor Migration

+
<TextBox ID="txtColor" />
+
+<div ID="pnlColorPicker" style="display: none;">
+    <div class="color-grid">
+        <span style="background: red;" onclick="commitColor('red')"></span>
+        <span style="background: blue;" onclick="commitColor('blue')"></span>
+        <span style="background: green;" onclick="commitColor('green')"></span>
+    </div>
+</div>
+
+<PopupControlExtender
+    TargetControlID="txtColor"
+    PopupControlID="pnlColorPicker"
+    Position="PopupPosition.Bottom"
+    CommitProperty="value"
+    CommitScript="onColorCommit()" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Use full enum type name for Position. Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the control that triggers the popup on click
PopupControlIDstring""ID of the panel element to display as a popup
PositionPopupPositionBottomPosition of the popup relative to the target: Left, Right, Top, Bottom, Center
OffsetXint0Horizontal offset in pixels from the calculated position
OffsetYint0Vertical offset in pixels from the calculated position
CommitPropertystring""Property name on the target control to set when the popup is committed (e.g., "value")
CommitScriptstring""JavaScript to execute when the popup is committed
ExtenderControlIDstring""ID for programmatic access to the extender
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Popup

+
@rendermode InteractiveServer
+
+<TextBox ID="txtInput" />
+
+<div ID="popupPanel" style="display: none; background: white; border: 1px solid #ccc; padding: 10px; border-radius: 4px;">
+    <p>Select an option:</p>
+    <button onclick="selectOption('Option A')">Option A</button>
+    <button onclick="selectOption('Option B')">Option B</button>
+</div>
+
+<PopupControlExtender
+    TargetControlID="txtInput"
+    PopupControlID="popupPanel"
+    Position="PopupPosition.Bottom" />
+
+ +
@rendermode InteractiveServer
+
+<TextBox ID="txtNote" />
+
+<div ID="notePopup" style="display: none; background: #fffbcc; border: 1px solid #e0d870; padding: 15px; width: 250px;">
+    <h4>Quick Notes</h4>
+    <textarea rows="3" style="width: 100%;"></textarea>
+    <button onclick="saveNote()">Save</button>
+</div>
+
+<PopupControlExtender
+    TargetControlID="txtNote"
+    PopupControlID="notePopup"
+    Position="PopupPosition.Right"
+    OffsetX="10"
+    OffsetY="-5" />
+
+ +

When a value is selected in the popup, it can be automatically set on the target control:

+
@rendermode InteractiveServer
+
+<TextBox ID="txtCategory" />
+
+<div ID="categoryPicker" style="display: none; background: white; border: 1px solid #ddd; padding: 8px;">
+    <ul style="list-style: none; padding: 0; margin: 0;">
+        <li style="padding: 4px 8px; cursor: pointer;" onclick="commitCategory('Electronics')">Electronics</li>
+        <li style="padding: 4px 8px; cursor: pointer;" onclick="commitCategory('Clothing')">Clothing</li>
+        <li style="padding: 4px 8px; cursor: pointer;" onclick="commitCategory('Books')">Books</li>
+    </ul>
+</div>
+
+<PopupControlExtender
+    TargetControlID="txtCategory"
+    PopupControlID="categoryPicker"
+    Position="PopupPosition.Bottom"
+    CommitProperty="value" />
+
+

HTML Output

+

The PopupControlExtender produces no HTML itself — it attaches JavaScript behavior to show/hide the popup panel and position it relative to the target control.

+

JavaScript Interop

+

The PopupControlExtender loads popup-control-extender.js as an ES module. JavaScript handles:

+
    +
  • Showing the popup when the target control is clicked
    • +
  • Positioning the popup relative to the target using the configured position and offsets
    • +
  • Dismissing the popup on outside click
    • +
  • Setting the commit property on the target when a value is committed
    • +
  • Executing the commit script
    • +
+

Render Mode Requirements

+

The PopupControlExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The popup panel remains hidden.
    • +
  • JavaScript disabled: Same as SSR — target control works normally without popup.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:PopupControlExtender
++ <PopupControlExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use full enum type name for Position + 

    - Position="Bottom"
++ Position="PopupPosition.Bottom"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtColor" runat="server" />
+
+<asp:Panel ID="pnlPicker" runat="server" style="display: none;">
+    <div>Color picker content</div>
+</asp:Panel>
+
+<ajaxToolkit:PopupControlExtender
+    ID="pce1"
+    TargetControlID="txtColor"
+    PopupControlID="pnlPicker"
+    Position="Bottom"
+    CommitProperty="value"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtColor" />
+
+<div ID="pnlPicker" style="display: none;">
+    <div>Color picker content</div>
+</div>
+
+<PopupControlExtender
+    TargetControlID="txtColor"
+    PopupControlID="pnlPicker"
+    Position="PopupPosition.Bottom"
+    CommitProperty="value" />
+
+

Best Practices

+
    +
  1. Hide the popup initially — Set style="display: none;" on the popup element
    2. +
  2. Use appropriate positioning — Choose Bottom for dropdowns, Right for sidebars
    3. +
  3. Fine-tune with offsets — Use OffsetX/OffsetY to avoid visual overlap
    4. +
  4. Keep popup content focused — Avoid overloading the popup with too much content
    5. +
  5. Use CommitProperty for form integration — Automatically set values on the target control
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Popup not appearingVerify TargetControlID and PopupControlID match their elements' IDs. Ensure @rendermode InteractiveServer is set.
Popup positioned incorrectlyTry a different Position value or adjust OffsetX/OffsetY.
Popup not dismissingEnsure there are no event propagation issues (e.g., stopPropagation calls) in the popup content.
Value not committedVerify CommitProperty matches the target's property name (typically "value" for inputs).
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/ResizableControlExtender/index.html b/site/AjaxToolkit/ResizableControlExtender/index.html new file mode 100644 index 000000000..429923d01 --- /dev/null +++ b/site/AjaxToolkit/ResizableControlExtender/index.html @@ -0,0 +1,5251 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ResizableControlExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ResizableControlExtender

+

The ResizableControlExtender allows users to resize an element by dragging its edges or a resize handle (typically positioned at the bottom-right corner). It supports optional minimum and maximum size constraints to prevent elements from becoming too small or too large.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/ResizableControlExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the element to make resizable
    • +
  • HandleCssClass — CSS class for the resize handle element
    • +
  • ResizableCssClass — CSS class applied while resizing
    • +
  • MinimumWidth — Minimum width constraint in pixels
    • +
  • MinimumHeight — Minimum height constraint in pixels
    • +
  • MaximumWidth — Maximum width constraint in pixels (0 = no limit)
    • +
  • MaximumHeight — Maximum height constraint in pixels (0 = no limit)
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Syntax

+
<asp:Panel ID="pnlResizable" runat="server" style="width: 300px; height: 200px; border: 1px solid black;">
+    <p>Resize me from the bottom-right corner!</p>
+    <div id="resizeHandle" class="resize-handle" style="position: absolute; bottom: 0; right: 0; width: 10px; height: 10px; background: #333; cursor: nwse-resize;"></div>
+</asp:Panel>
+
+<ajaxToolkit:ResizableControlExtender
+    ID="resize1"
+    runat="server"
+    TargetControlID="pnlResizable"
+    HandleCssClass="resize-handle"
+    MinimumWidth="100"
+    MinimumHeight="100"
+    MaximumWidth="600"
+    MaximumHeight="500" />
+
+

Blazor Migration

+
<Panel ID="pnlResizable" style="width: 300px; height: 200px; border: 1px solid black;">
+    <p>Resize me from the bottom-right corner!</p>
+    <div id="resizeHandle" class="resize-handle" style="position: absolute; bottom: 0; right: 0; width: 10px; height: 10px; background: #333; cursor: nwse-resize;"></div>
+</Panel>
+
+<ResizableControlExtender
+    TargetControlID="pnlResizable"
+    HandleCssClass="resize-handle"
+    MinimumWidth="100"
+    MinimumHeight="100"
+    MaximumWidth="600"
+    MaximumHeight="500" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the element to make resizable
HandleCssClassstring""CSS class for the resize handle element (usually positioned at bottom-right)
ResizableCssClassstring""CSS class applied to the target while it is being resized
MinimumWidthint0Minimum width constraint in pixels; 0 = no limit
MinimumHeightint0Minimum height constraint in pixels; 0 = no limit
MaximumWidthint0Maximum width constraint in pixels; 0 = no limit
MaximumHeightint0Maximum height constraint in pixels; 0 = no limit
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Resizable Panel

+
@rendermode InteractiveServer
+
+<Panel ID="pnlBox" style="width: 300px; height: 200px; border: 1px solid #ccc; padding: 10px; position: relative; overflow: auto;">
+    <p>Drag the handle in the corner to resize this panel.</p>
+    <div class="resize-handle"></div>
+</Panel>
+
+<ResizableControlExtender TargetControlID="pnlBox" HandleCssClass="resize-handle" />
+
+<style>
+    .resize-handle {
+        position: absolute;
+        bottom: 0;
+        right: 0;
+        width: 15px;
+        height: 15px;
+        background: #333;
+        cursor: nwse-resize;
+    }
+</style>
+
+

Resizable with Size Constraints

+
@rendermode InteractiveServer
+
+<Panel ID="pnlWindow" style="width: 400px; height: 300px; border: 2px solid #2196F3; position: relative; background: white;">
+    <div style="background: #2196F3; color: white; padding: 10px; font-weight: bold;">Resizable Window</div>
+    <div style="padding: 20px; overflow: auto; height: calc(100% - 50px);">
+        <p>Minimum size: 200x150px</p>
+        <p>Maximum size: 800x600px</p>
+    </div>
+    <div class="resize-corner"></div>
+</Panel>
+
+<ResizableControlExtender
+    TargetControlID="pnlWindow"
+    HandleCssClass="resize-corner"
+    MinimumWidth="200"
+    MinimumHeight="150"
+    MaximumWidth="800"
+    MaximumHeight="600"
+    ResizableCssClass="resizing" />
+
+<style>
+    .resize-corner {
+        position: absolute;
+        bottom: 0;
+        right: 0;
+        width: 20px;
+        height: 20px;
+        background: linear-gradient(135deg, transparent 50%, #2196F3 50%);
+        cursor: nwse-resize;
+    }
+
+    .resizing {
+        opacity: 0.8;
+    }
+</style>
+
+

Resizable Text Area

+
@rendermode InteractiveServer
+
+<Panel ID="pnlTextArea" style="width: 500px; height: 300px; position: relative; border: 1px solid #999;">
+    <TextArea ID="txtContent" style="width: 100%; height: 100%; border: none; padding: 10px; resize: none;"></TextArea>
+    <div class="resize-handle"></div>
+</Panel>
+
+<ResizableControlExtender
+    TargetControlID="pnlTextArea"
+    HandleCssClass="resize-handle"
+    MinimumWidth="250"
+    MinimumHeight="150"
+    MaximumWidth="1000"
+    MaximumHeight="800" />
+
+<style>
+    .resize-handle {
+        position: absolute;
+        bottom: 2px;
+        right: 2px;
+        width: 18px;
+        height: 18px;
+        background-image: repeating-linear-gradient(45deg, #ccc, #ccc 2px, transparent 2px, transparent 5px);
+        cursor: nwse-resize;
+    }
+</style>
+
+

HTML Output

+

The ResizableControlExtender produces no HTML itself — it attaches JavaScript behavior to the target element. You must provide the resize handle as part of your panel's HTML.

+

JavaScript Interop

+

The ResizableControlExtender loads resizable-control-extender.js as an ES module. JavaScript handles:

+
    +
  • Detecting mouse down on the resize handle
    • +
  • Tracking mouse movement while resizing
    • +
  • Updating the element's width and height in real-time
    • +
  • Enforcing minimum and maximum size constraints
    • +
  • Applying/removing resize CSS classes
    • +
  • Handling mouse up to stop resizing
    • +
  • Preventing text selection during resize
    • +
+

Render Mode Requirements

+

The ResizableControlExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The Panel displays at its initial size.
    • +
  • JavaScript disabled: Same as SSR — Panel is not resizable.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:ResizableControlExtender
++ <ResizableControlExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Size constraints use integers, not strings + 

    - MinimumWidth="200"
++ MinimumWidth="200"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Panel ID="pnlBox" runat="server" style="width: 300px; height: 200px; border: 1px solid black; position: relative;">
+    <p>Content</p>
+    <div class="handle"></div>
+</asp:Panel>
+
+<ajaxToolkit:ResizableControlExtender
+    ID="resize1"
+    TargetControlID="pnlBox"
+    HandleCssClass="handle"
+    MinimumWidth="150"
+    MaximumWidth="800"
+    runat="server" />
+
+

After (Blazor)

+
<Panel ID="pnlBox" style="width: 300px; height: 200px; border: 1px solid black; position: relative;">
+    <p>Content</p>
+    <div class="handle"></div>
+</Panel>
+
+<ResizableControlExtender
+    TargetControlID="pnlBox"
+    HandleCssClass="handle"
+    MinimumWidth="150"
+    MaximumWidth="800" />
+
+

Best Practices

+
    +
  1. Use position: relative or absolute — Ensure the target has proper positioning for the handle
    2. +
  2. Style the handle clearly — Make the resize handle visually obvious with contrasting colors
    3. +
  3. Set overflow: auto — Use overflow: auto on the panel so content scrolls when resized small
    4. +
  4. Provide constraints — Set reasonable min/max sizes to prevent broken layouts
    5. +
  5. Test edge cases — Verify behavior when resizing to minimum/maximum sizes
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Handle not visibleVerify HandleCssClass references a styled element within the panel. Check CSS positioning.
Resizing not workingEnsure @rendermode InteractiveServer is set and TargetControlID matches the panel's ID.
Size constraints ignoredVerify min/max values are integers and make sense (min < max). A value of 0 means no limit.
Content overlaps handleAdjust panel padding or use overflow: auto to prevent content overlap.
+

See Also

+
    +
  • Ajax Control Toolkit Overview — How extenders work and render mode requirements
    • +
  • Panel Component — The Panel control (documentation coming soon)
    • +
  • DragPanelExtender — Make panels draggable
    • +
  • Original Ajax Control Toolkit: https://www.asp.net/ajax/ajaxcontroltoolkit
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/RoundedCornersExtender/index.html b/site/AjaxToolkit/RoundedCornersExtender/index.html new file mode 100644 index 000000000..a71fe1eae --- /dev/null +++ b/site/AjaxToolkit/RoundedCornersExtender/index.html @@ -0,0 +1,5305 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + RoundedCornersExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

RoundedCornersExtender

+

The RoundedCornersExtender applies rounded corners to an element using CSS border-radius. It supports selecting which corners to round and optionally sets a background color for the rounded area, giving elements a modern, polished appearance.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/RoundedCornersExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the element to apply rounded corners to
    • +
  • Radius — Corner radius in pixels
    • +
  • Corners — Which corners to round (All, Top, Bottom, Left, Right, TopLeft, TopRight, BottomLeft, BottomRight, None)
    • +
  • Color — Background color for the rounded area
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

BoxCorners Enum

+

Specifies which corners to round (can be combined):

+
[Flags]
+enum BoxCorners
+{
+    None = 0,
+    TopLeft = 1,
+    TopRight = 2,
+    BottomLeft = 4,
+    BottomRight = 8,
+    Top = TopLeft | TopRight,      // Both top corners
+    Bottom = BottomLeft | BottomRight,  // Both bottom corners
+    Left = TopLeft | BottomLeft,   // Both left corners
+    Right = TopRight | BottomRight, // Both right corners
+    All = TopLeft | TopRight | BottomLeft | BottomRight  // All corners
+}
+
+

Web Forms Syntax

+
<asp:Panel ID="pnlBox" runat="server" style="width: 300px; padding: 20px; background-color: white; border: 1px solid #ccc;">
+    <p>This panel has rounded corners.</p>
+</asp:Panel>
+
+<ajaxToolkit:RoundedCornersExtender
+    ID="rounded1"
+    runat="server"
+    TargetControlID="pnlBox"
+    Radius="10"
+    Corners="All"
+    Color="#FFFFFF" />
+
+

Blazor Migration

+
<Panel ID="pnlBox" style="width: 300px; padding: 20px; background-color: white; border: 1px solid #ccc;">
+    <p>This panel has rounded corners.</p>
+</Panel>
+
+<RoundedCornersExtender
+    TargetControlID="pnlBox"
+    Radius="10"
+    Corners="BoxCorners.All"
+    Color="#FFFFFF" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Use enum type names for corners!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the element to apply rounded corners to
Radiusint5Corner radius in pixels
CornersBoxCornersAllSpecifies which corners to round
Colorstring""Background color for the rounded area (e.g., "#FFFFFF"); if empty, preserves element's background
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

All Corners Rounded

+
@rendermode InteractiveServer
+
+<Panel ID="pnlCard" style="width: 300px; padding: 20px; background-color: white; border: 1px solid #ddd;">
+    <h3>Card Title</h3>
+    <p>This panel has all corners rounded.</p>
+</Panel>
+
+<RoundedCornersExtender
+    TargetControlID="pnlCard"
+    Radius="10"
+    Corners="BoxCorners.All" />
+
+

Top Corners Only

+
@rendermode InteractiveServer
+
+<Panel ID="pnlHeader" style="width: 100%; padding: 15px; background: linear-gradient(to right, #2196F3, #1976D2); color: white;">
+    <h2>Section Header</h2>
+</Panel>
+
+<RoundedCornersExtender
+    TargetControlID="pnlHeader"
+    Radius="8"
+    Corners="BoxCorners.Top" />
+
+

Bottom Corners with Color

+
@rendermode InteractiveServer
+
+<Panel ID="pnlFooter" style="width: 100%; padding: 15px; background-color: #f5f5f5; border-top: 1px solid #ccc;">
+    <p>&copy; 2024 My Company. All rights reserved.</p>
+</Panel>
+
+<RoundedCornersExtender
+    TargetControlID="pnlFooter"
+    Radius="10"
+    Corners="BoxCorners.Bottom"
+    Color="#f5f5f5" />
+
+

Individual Corners

+
@rendermode InteractiveServer
+
+<Panel ID="pnlCustom" style="width: 250px; padding: 20px; background-color: white; border: 2px solid #FF9800;">
+    <p>Only bottom-right corner is rounded.</p>
+</Panel>
+
+<RoundedCornersExtender
+    TargetControlID="pnlCustom"
+    Radius="15"
+    Corners="BoxCorners.BottomRight" />
+
+

Large Radius for Button-Like Appearance

+
@rendermode InteractiveServer
+
+<Panel ID="pnlButton" style="width: 200px; padding: 15px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; text-align: center; cursor: pointer;">
+    <strong>Click Me!</strong>
+</Panel>
+
+<RoundedCornersExtender
+    TargetControlID="pnlButton"
+    Radius="25"
+    Corners="BoxCorners.All" />
+
+

HTML Output

+

The RoundedCornersExtender produces no HTML itself — it applies CSS border-radius styling to the target element.

+

JavaScript Interop

+

The RoundedCornersExtender loads rounded-corners-extender.js as an ES module. JavaScript handles:

+
    +
  • Applying CSS border-radius based on specified corners
    • +
  • Setting background color if provided
    • +
  • Handling older browsers that don't support border-radius
    • +
  • Calculating corner values based on the BoxCorners flags
    • +
+

Render Mode Requirements

+

The RoundedCornersExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. Use CSS border-radius as fallback.
    • +
  • JavaScript disabled: Same as SSR — Corners appear square unless CSS border-radius is present.
    • +
+

Modern Alternative (CSS-Only)

+

For most use cases, you can apply rounded corners directly with CSS without needing this extender:

+
<!-- Modern approach: Use CSS border-radius directly -->
+<Panel ID="pnlBox" style="width: 300px; padding: 20px; background-color: white; border: 1px solid #ccc; border-radius: 10px;">
+    <p>Rounded corners via CSS.</p>
+</Panel>
+
+

Use the RoundedCornersExtender primarily for dynamic scenarios or legacy component compatibility.

+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:RoundedCornersExtender
++ <RoundedCornersExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use enum types for corners + 

    - Corners="All"
++ Corners="BoxCorners.All"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Panel ID="pnlBox" runat="server" style="width: 300px; padding: 20px; background: white;">
+    <p>Content</p>
+</asp:Panel>
+
+<ajaxToolkit:RoundedCornersExtender
+    ID="rounded1"
+    TargetControlID="pnlBox"
+    Radius="10"
+    Corners="All"
+    runat="server" />
+
+

After (Blazor)

+
<Panel ID="pnlBox" style="width: 300px; padding: 20px; background: white;">
+    <p>Content</p>
+</Panel>
+
+<RoundedCornersExtender
+    TargetControlID="pnlBox"
+    Radius="10"
+    Corners="BoxCorners.All" />
+
+

Best Practices

+
    +
  1. Use CSS border-radius for modern browsers — The native CSS approach is simpler and more performant
    2. +
  2. Choose appropriate radius — 5-10px for subtle, 15-25px for more prominent rounding
    3. +
  3. Match corner selection to design — Use Top for headers, Bottom for footers, All for cards
    4. +
  4. Test across browsers — Most modern browsers support border-radius natively
    5. +
  5. Combine with other effects — Rounded corners pair well with shadows and borders
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Corners not roundingVerify TargetControlID matches the element's ID. Ensure @rendermode InteractiveServer is set.
Color shows gapsThe Color property is optional; ensure it matches or complements the element's background.
Performance issuesThis extender is rarely needed. Use CSS border-radius instead for better performance.
Old browser supportModern browsers support border-radius natively. This extender adds no value for modern web apps.
+

See Also

+
    +
  • Ajax Control Toolkit Overview — How extenders work and render mode requirements
    • +
  • Panel Component — The Panel control (documentation coming soon)
    • +
  • DropShadowExtender — Add drop shadows to elements
    • +
  • Original Ajax Control Toolkit: https://www.asp.net/ajax/ajaxcontroltoolkit
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/SlideShowExtender/index.html b/site/AjaxToolkit/SlideShowExtender/index.html new file mode 100644 index 000000000..173892ba4 --- /dev/null +++ b/site/AjaxToolkit/SlideShowExtender/index.html @@ -0,0 +1,5364 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + SlideShowExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

SlideShowExtender

+

The SlideShowExtender turns an Image control into an automatic slideshow that cycles through a collection of images. It supports automatic playback, manual navigation controls, optional image titles and descriptions, and looping. Images can be provided client-side as a collection or loaded from a service.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/SlideShowExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the Image control
    • +
  • Slides — Client-side collection of slides (IEnumerable)
    • +
  • AutoPlay — Whether to start playing automatically
    • +
  • Loop — Whether to loop back to first slide after last
    • +
  • PlayInterval — Interval in milliseconds between transitions
    • +
  • NextButtonID — ID of next button element
    • +
  • PreviousButtonID — ID of previous button element
    • +
  • PlayButtonID — ID of play/pause button element
    • +
  • PlayButtonText — Text for play button when paused
    • +
  • StopButtonText — Text for play button when playing
    • +
  • ImageTitleLabelID — ID of element for image titles
    • +
  • ImageDescriptionLabelID — ID of element for descriptions
    • +
  • SlideShowServicePath — Optional service URL for server-side slides
    • +
  • SlideShowServiceMethod — Service method name
    • +
  • ContextKey — Context key for service calls
    • +
+

Slide Model

+
public class SlideShowSlide
+{
+    public string ImageUrl { get; set; } = string.Empty;
+    public string Title { get; set; } = string.Empty;
+    public string Description { get; set; } = string.Empty;
+}
+
+

Web Forms Syntax

+
<asp:Image ID="imgSlide" runat="server" Width="400" Height="300" />
+
+<div>
+    <button id="btnPrev">Previous</button>
+    <button id="btnPlay">Play</button>
+    <button id="btnNext">Next</button>
+</div>
+
+<div id="lblTitle"></div>
+<div id="lblDescription"></div>
+
+<ajaxToolkit:SlideShowExtender
+    ID="slide1"
+    runat="server"
+    TargetControlID="imgSlide"
+    PlayInterval="3000"
+    AutoPlay="true"
+    Loop="true"
+    NextButtonID="btnNext"
+    PreviousButtonID="btnPrev"
+    PlayButtonID="btnPlay"
+    PlayButtonText="Play"
+    StopButtonText="Stop"
+    ImageTitleLabelID="lblTitle"
+    ImageDescriptionLabelID="lblDescription" />
+
+

Blazor Migration

+
<Image ID="imgSlide" width="400" height="300" />
+
+<div>
+    <button id="btnPrev">Previous</button>
+    <button id="btnPlay">Play</button>
+    <button id="btnNext">Next</button>
+</div>
+
+<div id="lblTitle"></div>
+<div id="lblDescription"></div>
+
+<SlideShowExtender
+    TargetControlID="imgSlide"
+    PlayInterval="3000"
+    AutoPlay="true"
+    Loop="true"
+    NextButtonID="btnNext"
+    PreviousButtonID="btnPrev"
+    PlayButtonID="btnPlay"
+    PlayButtonText="Play"
+    StopButtonText="Stop"
+    ImageTitleLabelID="lblTitle"
+    ImageDescriptionLabelID="lblDescription"
+    Slides="slides" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Pass slides via the Slides parameter!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the Image control
SlidesIEnumerable<SlideShowSlide>nullClient-side collection of slides to display
AutoPlayboolfalseWhether to start playing automatically
LoopbooltrueWhether to loop back to first slide after last
PlayIntervalint3000Interval in milliseconds between automatic transitions
NextButtonIDstring""ID of button element for next slide
PreviousButtonIDstring""ID of button element for previous slide
PlayButtonIDstring""ID of button element to toggle play/pause
PlayButtonTextstring"Play"Text for play button when slideshow is paused
StopButtonTextstring"Stop"Text for play button when slideshow is playing
ImageTitleLabelIDstring""ID of element to display current image title
ImageDescriptionLabelIDstring""ID of element to display current image description
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Slideshow with Navigation

+
@rendermode InteractiveServer
+
+@code {
+    private List<SlideShowSlide> slides = new()
+    {
+        new() { ImageUrl = "/images/slide1.jpg", Title = "Slide 1", Description = "First image" },
+        new() { ImageUrl = "/images/slide2.jpg", Title = "Slide 2", Description = "Second image" },
+        new() { ImageUrl = "/images/slide3.jpg", Title = "Slide 3", Description = "Third image" }
+    };
+}
+
+<div style="border: 1px solid #ccc; padding: 10px; text-align: center;">
+    <Image ID="imgSlideshow" width="500" height="350" style="display: block; margin: 0 auto;" />
+
+    <div id="slideTitle" style="font-size: 18px; font-weight: bold; margin: 10px 0;"></div>
+    <div id="slideDesc" style="color: #666; margin-bottom: 10px;"></div>
+
+    <div style="margin: 10px 0;">
+        <button id="btnPrev" class="btn btn-sm btn-secondary" style="margin-right: 5px;">← Previous</button>
+        <button id="btnPlay" class="btn btn-sm btn-primary">Play</button>
+        <button id="btnNext" class="btn btn-sm btn-secondary" style="margin-left: 5px;">Next →</button>
+    </div>
+</div>
+
+<SlideShowExtender
+    TargetControlID="imgSlideshow"
+    PlayInterval="3000"
+    AutoPlay="false"
+    Loop="true"
+    NextButtonID="btnNext"
+    PreviousButtonID="btnPrev"
+    PlayButtonID="btnPlay"
+    PlayButtonText="Play"
+    StopButtonText="Stop"
+    ImageTitleLabelID="slideTitle"
+    ImageDescriptionLabelID="slideDesc"
+    Slides="slides" />
+
+

Automatic Slideshow

+
@rendermode InteractiveServer
+
+@code {
+    private List<SlideShowSlide> productImages = new()
+    {
+        new() { ImageUrl = "/products/chair1.jpg", Title = "Chair - Side View" },
+        new() { ImageUrl = "/products/chair2.jpg", Title = "Chair - Front View" },
+        new() { ImageUrl = "/products/chair3.jpg", Title = "Chair - Detail" }
+    };
+}
+
+<div style="text-align: center; background-color: #f5f5f5; padding: 20px; border-radius: 5px;">
+    <Image ID="imgProduct" width="400" height="400" />
+    <h3 id="productTitle" style="margin: 10px 0;"></h3>
+</div>
+
+<SlideShowExtender
+    TargetControlID="imgProduct"
+    PlayInterval="2500"
+    AutoPlay="true"
+    Loop="true"
+    ImageTitleLabelID="productTitle"
+    Slides="productImages" />
+
+

Manual Navigation Only

+
@rendermode InteractiveServer
+
+@code {
+    private List<SlideShowSlide> gallerySlides = new()
+    {
+        new() { ImageUrl = "/gallery/img1.jpg", Title = "Sunset", Description = "Beautiful sunset over the ocean" },
+        new() { ImageUrl = "/gallery/img2.jpg", Title = "Mountain", Description = "Snow-capped mountain peaks" },
+        new() { ImageUrl = "/gallery/img3.jpg", Title = "Forest", Description = "Dense green forest" },
+        new() { ImageUrl = "/gallery/img4.jpg", Title = "Desert", Description = "Golden sand dunes" }
+    };
+}
+
+<div style="max-width: 600px; margin: 0 auto;">
+    <Image ID="imgGallery" width="100%" style="display: block; border: 1px solid #ddd;" />
+
+    <div id="galleryTitle" style="font-size: 20px; font-weight: bold; margin-top: 10px;"></div>
+    <div id="galleryDesc" style="color: #666; margin-bottom: 15px;"></div>
+
+    <div style="text-align: center;">
+        <button id="btnGalleryPrev" class="btn btn-primary" style="margin-right: 10px;">← Previous</button>
+        <button id="btnGalleryNext" class="btn btn-primary">Next →</button>
+    </div>
+</div>
+
+<SlideShowExtender
+    TargetControlID="imgGallery"
+    AutoPlay="false"
+    Loop="false"
+    NextButtonID="btnGalleryNext"
+    PreviousButtonID="btnGalleryPrev"
+    ImageTitleLabelID="galleryTitle"
+    ImageDescriptionLabelID="galleryDesc"
+    Slides="gallerySlides" />
+
+

HTML Output

+

The SlideShowExtender produces no HTML itself — it attaches JavaScript behavior to the target Image control and button elements.

+

JavaScript Interop

+

The SlideShowExtender loads slide-show-extender.js as an ES module. JavaScript handles:

+
    +
  • Managing slide collection (client-side or service-side)
    • +
  • Displaying images in sequence
    • +
  • Automatic playback with PlayInterval
    • +
  • Manual navigation via button clicks
    • +
  • Updating title and description labels
    • +
  • Play/pause toggle functionality
    • +
  • Looping behavior (restart from first slide or stop)
    • +
  • Button state management
    • +
+

Render Mode Requirements

+

The SlideShowExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. First image displays without slideshow.
    • +
  • JavaScript disabled: Same as SSR — No slideshow functionality.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:SlideShowExtender
++ <SlideShowExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Pass slides via parameter + 

    - Server-side slide data
++ Slides="slideList"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Image ID="imgSlide" runat="server" Width="400" Height="300" />
+
+<button id="btnPrev">Previous</button>
+<button id="btnPlay">Play</button>
+<button id="btnNext">Next</button>
+
+<ajaxToolkit:SlideShowExtender
+    ID="slide1"
+    TargetControlID="imgSlide"
+    PlayInterval="3000"
+    AutoPlay="true"
+    NextButtonID="btnNext"
+    PreviousButtonID="btnPrev"
+    PlayButtonID="btnPlay"
+    runat="server" />
+
+

After (Blazor)

+
<Image ID="imgSlide" width="400" height="300" />
+
+<button id="btnPrev">Previous</button>
+<button id="btnPlay">Play</button>
+<button id="btnNext">Next</button>
+
+<SlideShowExtender
+    TargetControlID="imgSlide"
+    PlayInterval="3000"
+    AutoPlay="true"
+    NextButtonID="btnNext"
+    PreviousButtonID="btnPrev"
+    PlayButtonID="btnPlay"
+    Slides="slides" />
+
+

Best Practices

+
    +
  1. Provide navigation buttons — Always include previous/next buttons even if autoplay is enabled
    2. +
  2. Set reasonable interval — 2500-4000ms typically works well for viewer comfort
    3. +
  3. Include titles and descriptions — Help viewers understand what they're seeing
    4. +
  4. Test with small/large collections — Verify performance with 5+ slides
    5. +
  5. Use high-quality images — Optimize images for web to ensure smooth transitions
    6. +
  6. Consider accessibility — Provide alternative text for images via titles
    7. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Slideshow not startingVerify TargetControlID matches the Image's ID and Slides parameter is populated. Ensure @rendermode InteractiveServer.
Buttons not workingEnsure button IDs in NextButtonID, PreviousButtonID, etc. match actual button element IDs.
Images not displayingVerify ImageUrl paths are correct and images are accessible. Check browser console for 404 errors.
Title/description not updatingVerify ImageTitleLabelID and ImageDescriptionLabelID match actual element IDs.
Autoplay not startingSet AutoPlay="true" and verify PlayInterval is a reasonable value (not 0).
+

See Also

+
    +
  • Ajax Control Toolkit Overview — How extenders work and render mode requirements
    • +
  • Image Component — The Image control (documentation coming soon)
    • +
  • Original Ajax Control Toolkit: https://www.asp.net/ajax/ajaxcontroltoolkit
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/SliderExtender/index.html b/site/AjaxToolkit/SliderExtender/index.html new file mode 100644 index 000000000..060b8e3cb --- /dev/null +++ b/site/AjaxToolkit/SliderExtender/index.html @@ -0,0 +1,5358 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + SliderExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

SliderExtender

+

The SliderExtender attaches range slider behavior to a target input element. Users can drag a handle along a rail to select a value within a range. It supports horizontal and vertical orientation, bound control synchronization, discrete steps, and customizable rail/handle appearance via CSS classes or image URLs.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/SliderExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the input element to enhance with slider behavior
    • +
  • Minimum — Minimum value of the slider range
    • +
  • Maximum — Maximum value of the slider range
    • +
  • Steps — Number of discrete steps (0 = continuous)
    • +
  • Value — Current value of the slider
    • +
  • BoundControlID — ID of another element synchronized with the slider value
    • +
  • Orientation — Horizontal or Vertical orientation
    • +
  • RailCssClass — CSS class for the slider rail/track
    • +
  • HandleCssClass — CSS class for the slider handle
    • +
  • HandleImageUrl — URL of an image to use for the handle
    • +
  • Length — Length of the slider in pixels
    • +
  • Decimals — Number of decimal places for the slider value
    • +
  • TooltipText — Tooltip template with {0} placeholder for the current value
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

SliderOrientation Enum

+
enum SliderOrientation
+{
+    Horizontal = 0,  // Left-to-right slider (default)
+    Vertical = 1     // Bottom-to-top slider
+}
+
+

Web Forms Syntax

+
<asp:TextBox ID="txtSlider" runat="server" />
+
+<ajaxToolkit:SliderExtender
+    ID="se1"
+    runat="server"
+    TargetControlID="txtSlider"
+    Minimum="0"
+    Maximum="100"
+    Steps="10"
+    RailCssClass="slider-rail"
+    HandleCssClass="slider-handle"
+    BoundControlID="lblValue"
+    TooltipText="Value: {0}" />
+
+<asp:Label ID="lblValue" runat="server" />
+
+

Blazor Migration

+
<TextBox ID="txtSlider" />
+
+<SliderExtender
+    TargetControlID="txtSlider"
+    Minimum="0"
+    Maximum="100"
+    Steps="10"
+    RailCssClass="slider-rail"
+    HandleCssClass="slider-handle"
+    BoundControlID="lblValue"
+    TooltipText="Value: {0}" />
+
+<Label ID="lblValue" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the input element to enhance with slider behavior
Minimumdouble0Minimum value of the slider range
Maximumdouble100Maximum value of the slider range
Stepsint0Number of discrete steps in the range; 0 means continuous
Valuedouble0Current value of the slider
BoundControlIDstring""ID of another element whose value is synchronized with the slider
OrientationSliderOrientationHorizontalSlider orientation: Horizontal or Vertical
RailCssClassstring""CSS class applied to the slider rail/track
HandleCssClassstring""CSS class applied to the slider handle
HandleImageUrlstring""URL of an image to use for the slider handle
Lengthint0Length of the slider in pixels
Decimalsint0Number of decimal places for the slider value
TooltipTextstring""Tooltip template displayed on hover; use {0} for the current value
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Horizontal Slider

+
@rendermode InteractiveServer
+
+<TextBox ID="txtVolume" />
+
+<SliderExtender
+    TargetControlID="txtVolume"
+    Minimum="0"
+    Maximum="100"
+    Value="50"
+    TooltipText="Volume: {0}%" />
+
+

Slider with Discrete Steps

+
@rendermode InteractiveServer
+
+<TextBox ID="txtRating" />
+
+<SliderExtender
+    TargetControlID="txtRating"
+    Minimum="1"
+    Maximum="5"
+    Steps="5"
+    Value="3"
+    TooltipText="Rating: {0} stars" />
+
+

Slider with Bound Label

+
@rendermode InteractiveServer
+
+<TextBox ID="txtBrightness" />
+
+<SliderExtender
+    TargetControlID="txtBrightness"
+    Minimum="0"
+    Maximum="100"
+    BoundControlID="lblBrightness"
+    RailCssClass="brightness-rail"
+    HandleCssClass="brightness-handle"
+    TooltipText="{0}%" />
+
+<Label ID="lblBrightness" Text="50" />
+
+<style>
+    .brightness-rail {
+        width: 300px; height: 6px;
+        background: linear-gradient(to right, #333, #fff);
+        border-radius: 3px;
+    }
+    .brightness-handle {
+        width: 20px; height: 20px;
+        background: #007bff; border-radius: 50%;
+        cursor: pointer;
+    }
+</style>
+
+

Vertical Slider

+
@rendermode InteractiveServer
+
+<TextBox ID="txtTemperature" />
+
+<SliderExtender
+    TargetControlID="txtTemperature"
+    Minimum="60"
+    Maximum="90"
+    Steps="0"
+    Decimals="1"
+    Orientation="SliderOrientation.Vertical"
+    Length="200"
+    TooltipText="{0}°F" />
+
+

Decimal Precision Slider

+
@rendermode InteractiveServer
+
+<TextBox ID="txtOpacity" />
+
+<SliderExtender
+    TargetControlID="txtOpacity"
+    Minimum="0"
+    Maximum="1"
+    Value="0.5"
+    Decimals="2"
+    TooltipText="Opacity: {0}" />
+
+

HTML Output

+

The SliderExtender produces no HTML itself — it attaches JavaScript behavior to the target input, creating a visual slider rail and handle in the DOM.

+

JavaScript Interop

+

The SliderExtender loads slider-extender.js as an ES module. JavaScript handles:

+
    +
  • Rendering the slider rail and handle elements
    • +
  • Mouse/touch drag interaction for value selection
    • +
  • Snapping to discrete steps when Steps > 0
    • +
  • Synchronizing the bound control's value
    • +
  • Tooltip display with formatted value
    • +
  • Horizontal and vertical orientation layout
    • +
+

Render Mode Requirements

+

The SliderExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The input works as a plain text field.
    • +
  • JavaScript disabled: Same as SSR — input functions without slider behavior.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:SliderExtender
++ <SliderExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use full enum type name for Orientation + 

    - Orientation="Vertical"
++ Orientation="SliderOrientation.Vertical"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtSlider" runat="server" />
+
+<ajaxToolkit:SliderExtender
+    ID="se1"
+    TargetControlID="txtSlider"
+    Minimum="0"
+    Maximum="100"
+    Steps="10"
+    BoundControlID="lblValue"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtSlider" />
+
+<SliderExtender
+    TargetControlID="txtSlider"
+    Minimum="0"
+    Maximum="100"
+    Steps="10"
+    BoundControlID="lblValue" />
+
+

Best Practices

+
    +
  1. Set a meaningful range — Use Minimum/Maximum that match your data
    2. +
  2. Use Steps for discrete values — Ratings, percentages in increments, etc.
    3. +
  3. Provide a tooltip — TooltipText with {0} gives users feedback while dragging
    4. +
  4. Bind to a label — BoundControlID shows the current value next to the slider
    5. +
  5. Style the rail and handle — Use RailCssClass and HandleCssClass for visual consistency
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Slider not appearingVerify TargetControlID matches the input's ID. Ensure @rendermode InteractiveServer is set.
Handle not draggableCheck for CSS overflow: hidden on parent containers that may clip the slider.
Value not updatingVerify BoundControlID matches the label's ID. Check that Steps isn't preventing the desired value.
Tooltip not showingEnsure TooltipText is set with {0} placeholder.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/TabContainer/index.html b/site/AjaxToolkit/TabContainer/index.html new file mode 100644 index 000000000..633391cbb --- /dev/null +++ b/site/AjaxToolkit/TabContainer/index.html @@ -0,0 +1,5429 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TabContainer - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

TabContainer

+

The TabContainer displays content in tabbed panels, where only the active tab's content is visible. Clicking a tab header switches the active tab. The companion TabPanel component defines each tab within the container.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/TabContainer

+

Features Supported in Blazor

+
    +
  • ActiveTabIndex — Zero-based index of the currently active tab
    • +
  • OnActiveTabChanged — Event raised when the active tab changes
    • +
  • OnClientActiveTabChanged — JavaScript function invoked when the active tab changes
    • +
  • ScrollBars — Specifies which scrollbars to display on the tab content area
    • +
  • CssClass — CSS class applied to the outer TabContainer div
    • +
  • ChildContent — Contains TabPanel child components
    • +
+

TabPanel Parameters

+
    +
  • HeaderText — Text displayed in this tab's header
    • +
  • HeaderTemplate — Custom RenderFragment for the tab header (takes precedence over HeaderText)
    • +
  • ContentTemplate — The content rendered in the tab panel body when active
    • +
  • Enabled — Whether this tab can be selected (disabled tabs are rendered but not clickable)
    • +
+

Web Forms Syntax

+
<ajaxToolkit:TabContainer
+    ID="tabs1"
+    runat="server"
+    ActiveTabIndex="0"
+    OnClientActiveTabChanged="onTabChanged"
+    ScrollBars="None"
+    CssClass="myTabs">
+    <ajaxToolkit:TabPanel ID="tab1" runat="server" HeaderText="General">
+        <ContentTemplate>
+            <p>General settings content.</p>
+        </ContentTemplate>
+    </ajaxToolkit:TabPanel>
+    <ajaxToolkit:TabPanel ID="tab2" runat="server" HeaderText="Advanced">
+        <ContentTemplate>
+            <p>Advanced settings content.</p>
+        </ContentTemplate>
+    </ajaxToolkit:TabPanel>
+    <ajaxToolkit:TabPanel ID="tab3" runat="server" HeaderText="About" Enabled="false">
+        <ContentTemplate>
+            <p>About information.</p>
+        </ContentTemplate>
+    </ajaxToolkit:TabPanel>
+</ajaxToolkit:TabContainer>
+
+

Blazor Migration

+
<TabContainer
+    ActiveTabIndex="0"
+    OnClientActiveTabChanged="onTabChanged"
+    ScrollBars="ScrollBars.None"
+    CssClass="myTabs">
+    <TabPanel HeaderText="General">
+        <ContentTemplate>
+            <p>General settings content.</p>
+        </ContentTemplate>
+    </TabPanel>
+    <TabPanel HeaderText="Advanced">
+        <ContentTemplate>
+            <p>Advanced settings content.</p>
+        </ContentTemplate>
+    </TabPanel>
+    <TabPanel HeaderText="About" Enabled="false">
+        <ContentTemplate>
+            <p>About information.</p>
+        </ContentTemplate>
+    </TabPanel>
+</TabContainer>
+
+

Migration is simple: Remove the ajaxToolkit: prefix, remove runat="server" and ID attributes. Everything else stays the same!

+

Properties Reference

+

TabContainer

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
ActiveTabIndexint0Zero-based index of the currently active tab
OnActiveTabChangedEventCallback<int>—Raised when the active tab changes
OnClientActiveTabChangedstring""Name of a client-side JavaScript function invoked when the active tab changes
ScrollBarsScrollBarsNoneSpecifies which scrollbars to display on the tab content area (None, Horizontal, Vertical, Both, Auto)
CssClassstring""CSS class applied to the outer TabContainer div
+

TabPanel

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
HeaderTextstring""Text displayed in this tab's header
HeaderTemplateRenderFragmentnullCustom header content (takes precedence over HeaderText)
ContentTemplateRenderFragmentnullContent rendered in the tab body when this tab is active
EnabledbooltrueWhether this tab can be selected. Disabled tabs are rendered but not clickable
+

Usage Examples

+

Basic Tab Container

+
@rendermode InteractiveServer
+
+<TabContainer ActiveTabIndex="0" CssClass="tab-demo">
+    <TabPanel HeaderText="Home">
+        <ContentTemplate>
+            <h3>Welcome</h3>
+            <p>This is the home tab content.</p>
+        </ContentTemplate>
+    </TabPanel>
+    <TabPanel HeaderText="Profile">
+        <ContentTemplate>
+            <h3>User Profile</h3>
+            <p>Profile information goes here.</p>
+        </ContentTemplate>
+    </TabPanel>
+    <TabPanel HeaderText="Settings">
+        <ContentTemplate>
+            <h3>Settings</h3>
+            <p>Application settings.</p>
+        </ContentTemplate>
+    </TabPanel>
+</TabContainer>
+
+

Tab Container with Custom Header Templates

+
@rendermode InteractiveServer
+
+<TabContainer ActiveTabIndex="0">
+    <TabPanel>
+        <HeaderTemplate>📧 <strong>Inbox</strong> (3)</HeaderTemplate>
+        <ContentTemplate>
+            <p>You have 3 new messages.</p>
+        </ContentTemplate>
+    </TabPanel>
+    <TabPanel>
+        <HeaderTemplate>📤 Sent</HeaderTemplate>
+        <ContentTemplate>
+            <p>Sent messages archive.</p>
+        </ContentTemplate>
+    </TabPanel>
+</TabContainer>
+
+

Tab Container with Disabled Tab

+
@rendermode InteractiveServer
+
+<TabContainer ActiveTabIndex="0" OnActiveTabChanged="OnTabChanged">
+    <TabPanel HeaderText="Step 1: Info">
+        <ContentTemplate>
+            <p>Enter your information.</p>
+        </ContentTemplate>
+    </TabPanel>
+    <TabPanel HeaderText="Step 2: Review" Enabled="@step2Enabled">
+        <ContentTemplate>
+            <p>Review your submission.</p>
+        </ContentTemplate>
+    </TabPanel>
+    <TabPanel HeaderText="Step 3: Confirm" Enabled="false">
+        <ContentTemplate>
+            <p>Confirm and submit.</p>
+        </ContentTemplate>
+    </TabPanel>
+</TabContainer>
+
+@code {
+    private bool step2Enabled = false;
+
+    void OnTabChanged(int index)
+    {
+        // Enable step 2 after visiting step 1
+        step2Enabled = true;
+    }
+}
+
+

Tab Container with JavaScript Callback

+
@rendermode InteractiveServer
+
+<TabContainer
+    ActiveTabIndex="0"
+    OnClientActiveTabChanged="handleTabChange">
+    <TabPanel HeaderText="Tab A">
+        <ContentTemplate><p>Content A</p></ContentTemplate>
+    </TabPanel>
+    <TabPanel HeaderText="Tab B">
+        <ContentTemplate><p>Content B</p></ContentTemplate>
+    </TabPanel>
+</TabContainer>
+
+<script>
+    function handleTabChange(tabIndex) {
+        console.log('Switched to tab:', tabIndex);
+    }
+</script>
+
+

HTML Output

+

The TabContainer renders a structured layout with a header strip and body area:

+
<div id="..." class="ajax__tab_container myTabs">
+    <!-- Tab header strip -->
+    <div class="ajax__tab_header" role="tablist">
+        <span class="ajax__tab_active" role="tab" aria-selected="true" style="cursor:pointer;">
+            General
+        </span>
+        <span class="ajax__tab_inactive" role="tab" aria-selected="false" style="cursor:pointer;">
+            Advanced
+        </span>
+        <span class="ajax__tab_inactive ajax__tab_disabled" role="tab" aria-selected="false">
+            About
+        </span>
+    </div>
+
+    <!-- Tab body area -->
+    <div class="ajax__tab_body">
+        <div class="ajax__tab_panel" role="tabpanel">
+            <p>General settings content.</p>
+        </div>
+        <div class="ajax__tab_panel" role="tabpanel" style="display:none;">
+            <p>Advanced settings content.</p>
+        </div>
+        <div class="ajax__tab_panel" role="tabpanel" style="display:none;">
+            <p>About information.</p>
+        </div>
+    </div>
+</div>
+
+

JavaScript Interop

+

The TabContainer loads tab-container.js as an ES module only when OnClientActiveTabChanged is set. JavaScript handles:

+
    +
  • invokeClientCallback() — Calls the named JavaScript function with the new tab index
    • +
+

Tab switching itself is handled entirely by Blazor; JavaScript is only used for the client callback feature.

+

Render Mode Requirements

+

The TabContainer works in all render modes for basic tab switching. InteractiveServer is required for:

+
    +
  • OnActiveTabChanged Blazor callback
    • +
  • OnClientActiveTabChanged JavaScript callback
    • +
+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: Tabs render correctly with the active tab visible. Tab switching won't work without interactivity.
    • +
  • JavaScript disabled: Tab switching works via Blazor server events, but OnClientActiveTabChanged won't fire.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:TabContainer
++ <TabContainer
+- <ajaxToolkit:TabPanel
++ <TabPanel
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Keep all properties the same — HeaderText, ContentTemplate, Enabled all work identically

    +
    4. +
+

Before (Web Forms)

+
<ajaxToolkit:TabContainer ID="tabs" runat="server" ActiveTabIndex="0">
+    <ajaxToolkit:TabPanel ID="tab1" runat="server" HeaderText="Tab 1">
+        <ContentTemplate><p>Content 1</p></ContentTemplate>
+    </ajaxToolkit:TabPanel>
+    <ajaxToolkit:TabPanel ID="tab2" runat="server" HeaderText="Tab 2">
+        <ContentTemplate><p>Content 2</p></ContentTemplate>
+    </ajaxToolkit:TabPanel>
+</ajaxToolkit:TabContainer>
+
+

After (Blazor)

+
<TabContainer ActiveTabIndex="0">
+    <TabPanel HeaderText="Tab 1">
+        <ContentTemplate><p>Content 1</p></ContentTemplate>
+    </TabPanel>
+    <TabPanel HeaderText="Tab 2">
+        <ContentTemplate><p>Content 2</p></ContentTemplate>
+    </TabPanel>
+</TabContainer>
+
+

Best Practices

+
    +
  1. Use meaningful tab labels — Keep headers short and descriptive
    2. +
  2. Set a sensible default tab — ActiveTabIndex="0" shows the first tab
    3. +
  3. Disable tabs logically — Use Enabled="false" for wizard-like step progression
    4. +
  4. Use HeaderTemplate for rich headers — Add icons or badges when plain text isn't enough
    5. +
  5. Accessibility — Tab headers use role="tab" and aria-selected automatically
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
No tabs visibleVerify TabPanel components are direct children of TabContainer. Check that at least one TabPanel exists.
Tab click does nothingEnsure @rendermode InteractiveServer is set. Check that the tab's Enabled property is true.
TabPanel throws exceptionTabPanel must be inside a TabContainer. Verify the nesting structure.
Client callback not firingVerify OnClientActiveTabChanged names a valid global JavaScript function. Check browser console for errors.
Scrollbars not appearingSet ScrollBars to Vertical, Horizontal, Both, or Auto. Ensure content overflows the container.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/TextBoxWatermarkExtender/index.html b/site/AjaxToolkit/TextBoxWatermarkExtender/index.html new file mode 100644 index 000000000..972bc967e --- /dev/null +++ b/site/AjaxToolkit/TextBoxWatermarkExtender/index.html @@ -0,0 +1,5151 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TextBoxWatermarkExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

TextBoxWatermarkExtender

+

The TextBoxWatermarkExtender displays a placeholder or watermark text in a TextBox when it is empty. The watermark text appears in a distinct style (via CSS class) and automatically disappears when the user focuses the field or begins typing. It reappears when the field is cleared.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/TextBoxWatermarkExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the TextBox to attach the watermark to
    • +
  • WatermarkText — The placeholder text to display when empty
    • +
  • WatermarkCssClass — CSS class applied to the TextBox when showing the watermark
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Syntax

+
<asp:TextBox ID="txtSearch" runat="server" />
+
+<ajaxToolkit:TextBoxWatermarkExtender
+    ID="watermark1"
+    runat="server"
+    TargetControlID="txtSearch"
+    WatermarkText="Search..."
+    WatermarkCssClass="watermark-style" />
+
+

Blazor Migration

+
<TextBox ID="txtSearch" />
+
+<TextBoxWatermarkExtender
+    TargetControlID="txtSearch"
+    WatermarkText="Search..."
+    WatermarkCssClass="watermark-style" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the TextBox to attach the watermark to
WatermarkTextstring""The placeholder/watermark text to display when the TextBox is empty
WatermarkCssClassstring""CSS class applied to the TextBox when showing the watermark
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Watermark

+
@rendermode InteractiveServer
+
+<TextBox ID="txtEmail" />
+
+<TextBoxWatermarkExtender
+    TargetControlID="txtEmail"
+    WatermarkText="Enter your email..." />
+
+

Watermark with Custom Styling

+
@rendermode InteractiveServer
+
+<TextBox ID="txtComment" />
+
+<TextBoxWatermarkExtender
+    TargetControlID="txtComment"
+    WatermarkText="Add a comment..."
+    WatermarkCssClass="input-watermark" />
+
+<style>
+    .input-watermark {
+        color: #999;
+        font-style: italic;
+        opacity: 0.7;
+    }
+</style>
+
+

Multiple Watermarks

+
@rendermode InteractiveServer
+
+<TextBox ID="txtFirst" />
+<TextBoxWatermarkExtender
+    TargetControlID="txtFirst"
+    WatermarkText="First name"
+    WatermarkCssClass="watermark" />
+
+<TextBox ID="txtLast" />
+<TextBoxWatermarkExtender
+    TargetControlID="txtLast"
+    WatermarkText="Last name"
+    WatermarkCssClass="watermark" />
+
+

HTML Output

+

The TextBoxWatermarkExtender produces no HTML itself — it attaches JavaScript behavior to the target TextBox. The watermark text is managed entirely by JavaScript.

+

JavaScript Interop

+

The TextBoxWatermarkExtender loads textbox-watermark-extender.js as an ES module. JavaScript handles:

+
    +
  • Displaying/hiding watermark text on focus
    • +
  • Clearing watermark when user types
    • +
  • Re-displaying watermark when field is cleared
    • +
  • Applying/removing CSS classes based on watermark state
    • +
  • Preserving the user's actual input value
    • +
+

Render Mode Requirements

+

The TextBoxWatermarkExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The TextBox works as a plain text input without watermark.
    • +
  • JavaScript disabled: Same as SSR — TextBox functions without watermark display.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:TextBoxWatermarkExtender
++ <TextBoxWatermarkExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    CSS classes stay the same + 

    - WatermarkCssClass="watermark-style"
++ WatermarkCssClass="watermark-style"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtSearch" runat="server" />
+
+<ajaxToolkit:TextBoxWatermarkExtender
+    ID="watermark1"
+    TargetControlID="txtSearch"
+    WatermarkText="Type to search..."
+    WatermarkCssClass="watermark"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtSearch" />
+
+<TextBoxWatermarkExtender
+    TargetControlID="txtSearch"
+    WatermarkText="Type to search..."
+    WatermarkCssClass="watermark" />
+
+

Best Practices

+
    +
  1. Use descriptive watermark text — Make it clear what the field expects (e.g., "Enter email address" vs "Email")
    2. +
  2. Apply distinguishing CSS — Use color, opacity, or font-style to visually separate watermark from user input
    3. +
  3. Keep it short — Long watermark text may be cut off in small fields
    4. +
  4. Test with empty forms — Ensure watermark appears correctly on page load
    5. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Watermark not appearingVerify TargetControlID matches the TextBox's ID. Ensure @rendermode InteractiveServer is set.
Watermark text stays with inputCheck CSS class styling. The JavaScript manages visibility, but CSS should distinguish watermark visually.
Watermark doesn't disappear when typingEnsure JavaScript is enabled and textbox-watermark-extender.js loads successfully.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/ToggleButtonExtender/index.html b/site/AjaxToolkit/ToggleButtonExtender/index.html new file mode 100644 index 000000000..18720c049 --- /dev/null +++ b/site/AjaxToolkit/ToggleButtonExtender/index.html @@ -0,0 +1,5230 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ToggleButtonExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ToggleButtonExtender

+

The ToggleButtonExtender replaces a target checkbox with a clickable image that toggles between checked and unchecked states. It supports separate images for checked, unchecked, hover, and disabled states, providing a visually rich alternative to standard checkboxes.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/ToggleButtonExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the checkbox to enhance with toggle image behavior
    • +
  • ImageWidth — Width of the toggle image in pixels
    • +
  • ImageHeight — Height of the toggle image in pixels
    • +
  • UncheckedImageUrl — Image URL for the unchecked state
    • +
  • CheckedImageUrl — Image URL for the checked state
    • +
  • UncheckedImageAlternateText — Alt text for the unchecked image
    • +
  • CheckedImageAlternateText — Alt text for the checked image
    • +
  • CheckedImageOverUrl — Hover image URL when checked
    • +
  • UncheckedImageOverUrl — Hover image URL when unchecked
    • +
  • DisabledUncheckedImageUrl — Image URL when disabled and unchecked
    • +
  • DisabledCheckedImageUrl — Image URL when disabled and checked
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Syntax

+
<asp:CheckBox ID="chkSubscribe" runat="server" />
+
+<ajaxToolkit:ToggleButtonExtender
+    ID="tbe1"
+    runat="server"
+    TargetControlID="chkSubscribe"
+    ImageWidth="24"
+    ImageHeight="24"
+    UncheckedImageUrl="~/images/toggle-off.png"
+    CheckedImageUrl="~/images/toggle-on.png"
+    UncheckedImageAlternateText="Not subscribed"
+    CheckedImageAlternateText="Subscribed"
+    CheckedImageOverUrl="~/images/toggle-on-hover.png"
+    UncheckedImageOverUrl="~/images/toggle-off-hover.png" />
+
+

Blazor Migration

+
<CheckBox ID="chkSubscribe" />
+
+<ToggleButtonExtender
+    TargetControlID="chkSubscribe"
+    ImageWidth="24"
+    ImageHeight="24"
+    UncheckedImageUrl="/images/toggle-off.png"
+    CheckedImageUrl="/images/toggle-on.png"
+    UncheckedImageAlternateText="Not subscribed"
+    CheckedImageAlternateText="Subscribed"
+    CheckedImageOverUrl="/images/toggle-on-hover.png"
+    UncheckedImageOverUrl="/images/toggle-off-hover.png" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Update image paths from ~/ to /. Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the checkbox to enhance with toggle image behavior
ImageWidthint0Width of the toggle image in pixels
ImageHeightint0Height of the toggle image in pixels
UncheckedImageUrlstring""URL of the image displayed when the checkbox is unchecked
CheckedImageUrlstring""URL of the image displayed when the checkbox is checked
UncheckedImageAlternateTextstring""Alternate text for the unchecked image (accessibility)
CheckedImageAlternateTextstring""Alternate text for the checked image (accessibility)
CheckedImageOverUrlstring""URL of the image displayed on hover when checked
UncheckedImageOverUrlstring""URL of the image displayed on hover when unchecked
DisabledUncheckedImageUrlstring""URL of the image displayed when disabled and unchecked
DisabledCheckedImageUrlstring""URL of the image displayed when disabled and checked
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Toggle Button

+
@rendermode InteractiveServer
+
+<CheckBox ID="chkNotifications" />
+
+<ToggleButtonExtender
+    TargetControlID="chkNotifications"
+    ImageWidth="48"
+    ImageHeight="24"
+    UncheckedImageUrl="/images/switch-off.png"
+    CheckedImageUrl="/images/switch-on.png"
+    UncheckedImageAlternateText="Notifications off"
+    CheckedImageAlternateText="Notifications on" />
+
+

Toggle with Hover States

+
@rendermode InteractiveServer
+
+<CheckBox ID="chkFavorite" />
+
+<ToggleButtonExtender
+    TargetControlID="chkFavorite"
+    ImageWidth="32"
+    ImageHeight="32"
+    UncheckedImageUrl="/images/star-empty.png"
+    CheckedImageUrl="/images/star-filled.png"
+    UncheckedImageOverUrl="/images/star-empty-hover.png"
+    CheckedImageOverUrl="/images/star-filled-hover.png"
+    UncheckedImageAlternateText="Add to favorites"
+    CheckedImageAlternateText="Remove from favorites" />
+
+

Toggle with Disabled States

+
@rendermode InteractiveServer
+
+<CheckBox ID="chkFeature" Enabled="false" />
+
+<ToggleButtonExtender
+    TargetControlID="chkFeature"
+    ImageWidth="48"
+    ImageHeight="24"
+    UncheckedImageUrl="/images/toggle-off.png"
+    CheckedImageUrl="/images/toggle-on.png"
+    DisabledUncheckedImageUrl="/images/toggle-off-disabled.png"
+    DisabledCheckedImageUrl="/images/toggle-on-disabled.png" />
+
+

HTML Output

+

The ToggleButtonExtender produces no HTML itself — it attaches JavaScript behavior that replaces the checkbox's visual appearance with an image element while preserving the checkbox's checked/unchecked state.

+

JavaScript Interop

+

The ToggleButtonExtender loads toggle-button-extender.js as an ES module. JavaScript handles:

+
    +
  • Hiding the original checkbox and displaying an image in its place
    • +
  • Swapping images on click (checked ↔ unchecked)
    • +
  • Swapping images on hover (over states)
    • +
  • Displaying disabled images when the checkbox is disabled
    • +
  • Keeping the underlying checkbox state in sync
    • +
+

Render Mode Requirements

+

The ToggleButtonExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. The standard checkbox is displayed.
    • +
  • JavaScript disabled: Same as SSR — standard checkbox functions normally.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:ToggleButtonExtender
++ <ToggleButtonExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Update image paths from ~/ syntax to / paths + 

    - UncheckedImageUrl="~/images/toggle-off.png"
++ UncheckedImageUrl="/images/toggle-off.png"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:CheckBox ID="chkAgree" runat="server" />
+
+<ajaxToolkit:ToggleButtonExtender
+    ID="tbe1"
+    TargetControlID="chkAgree"
+    ImageWidth="24"
+    ImageHeight="24"
+    UncheckedImageUrl="~/images/unchecked.png"
+    CheckedImageUrl="~/images/checked.png"
+    runat="server" />
+
+

After (Blazor)

+
<CheckBox ID="chkAgree" />
+
+<ToggleButtonExtender
+    TargetControlID="chkAgree"
+    ImageWidth="24"
+    ImageHeight="24"
+    UncheckedImageUrl="/images/unchecked.png"
+    CheckedImageUrl="/images/checked.png" />
+
+

Best Practices

+
    +
  1. Always provide alt text — Set UncheckedImageAlternateText and CheckedImageAlternateText for accessibility
    2. +
  2. Use consistent image sizes — Set ImageWidth and ImageHeight to prevent layout shifts
    3. +
  3. Provide hover states — CheckedImageOverUrl and UncheckedImageOverUrl improve visual feedback
    4. +
  4. Include disabled states — If your checkbox can be disabled, provide DisabledCheckedImageUrl and DisabledUncheckedImageUrl
    5. +
  5. Optimize images — Use small, optimized PNG or SVG images for fast loading
    6. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Image not appearingVerify CheckedImageUrl and UncheckedImageUrl point to valid image files. Ensure @rendermode InteractiveServer is set.
Standard checkbox still visibleCheck that TargetControlID matches the checkbox's ID exactly.
Hover state not workingVerify CheckedImageOverUrl and UncheckedImageOverUrl paths are correct.
Toggle state not syncingEnsure the target is a checkbox element. Check browser console for JavaScript errors.
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/UpdatePanelAnimationExtender/index.html b/site/AjaxToolkit/UpdatePanelAnimationExtender/index.html new file mode 100644 index 000000000..352160d16 --- /dev/null +++ b/site/AjaxToolkit/UpdatePanelAnimationExtender/index.html @@ -0,0 +1,5311 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + UpdatePanelAnimationExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

UpdatePanelAnimationExtender

+

The UpdatePanelAnimationExtender provides visual feedback animations when content is updating. It applies CSS classes and fade effects during loading and after updates complete, giving users clear indication that content is being refreshed. Useful for async operations and dynamic content loading.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/UpdatePanelAnimationExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the panel or container to animate
    • +
  • AlwaysFinishOnUpdatingAnimation — Whether to complete the "updating" animation before starting "updated"
    • +
  • OnUpdatingCssClass — CSS class to apply during update/loading state
    • +
  • OnUpdatedCssClass — CSS class to apply after update completes
    • +
  • FadeInDuration — Duration of the fade-in effect in seconds
    • +
  • FadeOutDuration — Duration of the fade-out effect in seconds
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

Web Forms Syntax

+
<asp:Panel ID="pnlContent" runat="server">
+    <p>Updating content...</p>
+</asp:Panel>
+
+<ajaxToolkit:UpdatePanelAnimationExtender
+    ID="anim1"
+    runat="server"
+    TargetControlID="pnlContent"
+    OnUpdatingCssClass="updating"
+    OnUpdatedCssClass="updated"
+    FadeOutDuration="0.3"
+    FadeInDuration="0.3" />
+
+

Blazor Migration

+
<Panel ID="pnlContent">
+    <p>Updating content...</p>
+</Panel>
+
+<UpdatePanelAnimationExtender
+    TargetControlID="pnlContent"
+    OnUpdatingCssClass="updating"
+    OnUpdatedCssClass="updated"
+    FadeOutDuration="0.3"
+    FadeInDuration="0.3" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Everything else stays the same!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the panel or container to animate
AlwaysFinishOnUpdatingAnimationboolfalseWhether to complete the "updating" animation before starting the "updated" animation
OnUpdatingCssClassstring""CSS class to apply during update/loading state
OnUpdatedCssClassstring""CSS class to apply after update completes
FadeInDurationdouble0.3Duration in seconds for the fade-in effect after update completes
FadeOutDurationdouble0.3Duration in seconds for the fade-out effect before update starts
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Update Animation

+
@rendermode InteractiveServer
+
+<Panel ID="pnlData" style="padding: 20px; background-color: white; border: 1px solid #ccc;">
+    <p>Content loaded</p>
+</Panel>
+
+<UpdatePanelAnimationExtender
+    TargetControlID="pnlData"
+    OnUpdatingCssClass="loading"
+    OnUpdatedCssClass="loaded"
+    FadeOutDuration="0.2"
+    FadeInDuration="0.3" />
+
+<style>
+    .loading {
+        opacity: 0.5;
+        background-color: #f5f5f5;
+    }
+
+    .loaded {
+        background-color: #e8f5e9;
+    }
+</style>
+
+

Loading Spinner Animation

+
@rendermode InteractiveServer
+
+<Panel ID="pnlResults" style="padding: 20px;">
+    <p>Results will appear here...</p>
+</Panel>
+
+<UpdatePanelAnimationExtender
+    TargetControlID="pnlResults"
+    OnUpdatingCssClass="updating-with-spinner"
+    OnUpdatedCssClass="update-complete"
+    FadeOutDuration="0.2"
+    FadeInDuration="0.5" />
+
+<style>
+    .updating-with-spinner {
+        position: relative;
+        pointer-events: none;
+    }
+
+    .updating-with-spinner::before {
+        content: '';
+        position: absolute;
+        top: 50%;
+        left: 50%;
+        transform: translate(-50%, -50%);
+        width: 30px;
+        height: 30px;
+        border: 3px solid #f3f3f3;
+        border-top: 3px solid #2196F3;
+        border-radius: 50%;
+        animation: spin 1s linear infinite;
+    }
+
+    @keyframes spin {
+        0% { transform: translate(-50%, -50%) rotate(0deg); }
+        100% { transform: translate(-50%, -50%) rotate(360deg); }
+    }
+
+    .update-complete {
+        background-color: #c8e6c9;
+        border: 1px solid #4caf50;
+    }
+</style>
+
+

Gradient Fade Effect

+
@rendermode InteractiveServer
+
+<Panel ID="pnlInfo" style="padding: 20px; background-color: white; border-radius: 5px;">
+    <p>Information updated</p>
+</Panel>
+
+<UpdatePanelAnimationExtender
+    TargetControlID="pnlInfo"
+    OnUpdatingCssClass="fade-out"
+    OnUpdatedCssClass="fade-in"
+    FadeOutDuration="0.3"
+    FadeInDuration="0.5"
+    AlwaysFinishOnUpdatingAnimation="true" />
+
+<style>
+    @@keyframes fadeOut {
+        from { opacity: 1; }
+        to { opacity: 0.3; }
+    }
+
+    @@keyframes fadeIn {
+        from { opacity: 0.3; }
+        to { opacity: 1; }
+    }
+
+    .fade-out {
+        animation: fadeOut 0.3s ease-out forwards;
+    }
+
+    .fade-in {
+        animation: fadeIn 0.5s ease-in forwards;
+    }
+</style>
+
+

Color Pulse Animation

+
@rendermode InteractiveServer
+
+<Panel ID="pnlNotification" style="padding: 20px; background-color: white; border-left: 4px solid #2196F3;">
+    <p>Status updated</p>
+</Panel>
+
+<UpdatePanelAnimationExtender
+    TargetControlID="pnlNotification"
+    OnUpdatingCssClass="pulse-updating"
+    OnUpdatedCssClass="pulse-updated"
+    FadeOutDuration="0.2"
+    FadeInDuration="0.4" />
+
+<style>
+    @@keyframes pulse {
+        0% { background-color: white; }
+        50% { background-color: #E3F2FD; }
+        100% { background-color: white; }
+    }
+
+    .pulse-updating {
+        animation: pulse 0.6s ease-in-out;
+        opacity: 0.7;
+    }
+
+    .pulse-updated {
+        animation: pulse 0.8s ease-in-out 2;
+    }
+</style>
+
+

HTML Output

+

The UpdatePanelAnimationExtender produces no HTML itself — it attaches JavaScript behavior to the target panel, applying CSS classes based on update state.

+

JavaScript Interop

+

The UpdatePanelAnimationExtender loads update-panel-animation-extender.js as an ES module. JavaScript handles:

+
    +
  • Detecting content update events
    • +
  • Applying "updating" CSS class when update begins
    • +
  • Removing "updating" class when complete
    • +
  • Applying "updated" CSS class after update
    • +
  • Fade effects using opacity transitions
    • +
  • Sequencing animations if AlwaysFinishOnUpdatingAnimation is enabled
    • +
  • Managing animation timing and duration
    • +
+

Render Mode Requirements

+

The UpdatePanelAnimationExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. Panel updates occur without animation.
    • +
  • JavaScript disabled: Same as SSR — No animations are applied.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:UpdatePanelAnimationExtender
++ <UpdatePanelAnimationExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    CSS classes and animation durations stay the same + 

    - FadeOutDuration="0.3"
++ FadeOutDuration="0.3"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:Panel ID="pnlData" runat="server">
+    <p>Content</p>
+</asp:Panel>
+
+<ajaxToolkit:UpdatePanelAnimationExtender
+    ID="anim1"
+    TargetControlID="pnlData"
+    OnUpdatingCssClass="loading"
+    OnUpdatedCssClass="loaded"
+    FadeOutDuration="0.3"
+    FadeInDuration="0.3"
+    runat="server" />
+
+

After (Blazor)

+
<Panel ID="pnlData">
+    <p>Content</p>
+</Panel>
+
+<UpdatePanelAnimationExtender
+    TargetControlID="pnlData"
+    OnUpdatingCssClass="loading"
+    OnUpdatedCssClass="loaded"
+    FadeOutDuration="0.3"
+    FadeInDuration="0.3" />
+
+

Best Practices

+
    +
  1. Keep animations short — Use 0.2-0.5 seconds for snappy feel; longer durations can feel sluggish
    2. +
  2. Use meaningful CSS classes — Make updating/updated states visually distinct
    3. +
  3. Avoid blocking interactions — Use pointer-events: none during updates if appropriate
    4. +
  4. Test with slow networks — Ensure animations work well even with delayed updates
    5. +
  5. Combine with loading indicators — Show spinners or progress during the updating state
    6. +
  6. Use AlwaysFinishOnUpdatingAnimation carefully — Only enable if you need sequential animations
    7. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Animations not appearingVerify TargetControlID matches the panel's ID. Ensure @rendermode InteractiveServer is set. Define CSS classes.
Animation timing seems offAdjust FadeOutDuration and FadeInDuration values. Try 0.2-0.5 seconds for best results.
CSS classes not appliedVerify the CSS class names in OnUpdatingCssClass and OnUpdatedCssClass are defined in your stylesheets.
Content blocked during updateIf content should remain clickable, avoid pointer-events: none or set it only on specific elements.
+

See Also

+
    +
  • Ajax Control Toolkit Overview — How extenders work and render mode requirements
    • +
  • Panel Component — The Panel control (documentation coming soon)
    • +
  • Original Ajax Control Toolkit: https://www.asp.net/ajax/ajaxcontroltoolkit
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/ValidatorCalloutExtender/index.html b/site/AjaxToolkit/ValidatorCalloutExtender/index.html new file mode 100644 index 000000000..3766b7f84 --- /dev/null +++ b/site/AjaxToolkit/ValidatorCalloutExtender/index.html @@ -0,0 +1,5368 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ValidatorCalloutExtender - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ValidatorCalloutExtender

+

The ValidatorCalloutExtender enhances ASP.NET validators by displaying validation messages in a callout or tooltip bubble instead of inline error text. It attaches to a validator control and displays its error message in a styled popup positioned near the invalid field, with an optional close button and warning icon.

+

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/ValidatorCalloutExtender

+

Features Supported in Blazor

+
    +
  • TargetControlID — ID of the validator control to enhance
    • +
  • Width — Callout width in pixels
    • +
  • HighlightCssClass — CSS class to apply to invalid fields
    • +
  • WarningIconImageUrl — URL to warning icon image
    • +
  • CloseImageUrl — URL to close button image
    • +
  • CssClass — CSS class for the callout container
    • +
  • PopupPosition — Position of the callout (Left, Right, Top, Bottom, Center, TopLeft, TopRight, BottomLeft, BottomRight)
    • +
  • Enabled — Enable or disable the extender behavior
    • +
  • BehaviorID — Optional identifier for JavaScript behavior lookup
    • +
+

PopupPosition Enum

+

Controls where the callout appears:

+
enum PopupPosition
+{
+    Left = 0,
+    Right = 1,
+    Top = 2,
+    Bottom = 3,
+    Center = 4,
+    TopLeft = 5,
+    TopRight = 6,
+    BottomLeft = 7,
+    BottomRight = 8
+}
+
+

Web Forms Syntax

+
<asp:TextBox ID="txtEmail" runat="server" />
+
+<asp:RequiredFieldValidator
+    ID="valEmail"
+    ControlToValidate="txtEmail"
+    ErrorMessage="Email is required"
+    runat="server" />
+
+<ajaxToolkit:ValidatorCalloutExtender
+    ID="val1"
+    runat="server"
+    TargetControlID="valEmail"
+    PopupPosition="TopRight"
+    Width="250"
+    HighlightCssClass="field-error"
+    WarningIconImageUrl="~/images/warning.png"
+    CloseImageUrl="~/images/close.png" />
+
+

Blazor Migration

+
<TextBox ID="txtEmail" />
+
+<RequiredFieldValidator
+    ID="valEmail"
+    ControlToValidate="txtEmail"
+    ErrorMessage="Email is required" />
+
+<ValidatorCalloutExtender
+    TargetControlID="valEmail"
+    PopupPosition="PopupPosition.TopRight"
+    Width="250"
+    HighlightCssClass="field-error"
+    WarningIconImageUrl="~/images/warning.png"
+    CloseImageUrl="~/images/close.png" />
+
+

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Use enum type names for positions!

+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the validator control to enhance
Widthint250Callout width in pixels
HighlightCssClassstring""CSS class to apply to the invalid input field
WarningIconImageUrlstring""URL to the warning icon image displayed in the callout
CloseImageUrlstring""URL to the close button image (if provided, close button appears)
CssClassstring""CSS class applied to the callout container
PopupPositionPopupPositionBottomLeftPosition of the callout relative to the invalid field
BehaviorIDstringTargetControlIDOptional identifier for JavaScript behavior lookup
EnabledbooltrueWhether the extender is active
+

Usage Examples

+

Basic Validator Callout

+
@rendermode InteractiveServer
+
+<form>
+    <div>
+        <label>Email:</label>
+        <TextBox ID="txtEmail" type="email" style="width: 200px;" />
+
+        <RequiredFieldValidator
+            ID="valEmail"
+            ControlToValidate="txtEmail"
+            ErrorMessage="Email address is required" />
+
+        <ValidatorCalloutExtender
+            TargetControlID="valEmail"
+            PopupPosition="PopupPosition.TopRight"
+            Width="250" />
+    </div>
+
+    <button type="submit" class="btn btn-primary">Submit</button>
+</form>
+
+

Callout with Custom Styling

+
@rendermode InteractiveServer
+
+<form>
+    <div>
+        <label>Username:</label>
+        <TextBox ID="txtUsername" style="width: 200px;" />
+
+        <RequiredFieldValidator
+            ID="valUsername"
+            ControlToValidate="txtUsername"
+            ErrorMessage="Username is required" />
+
+        <ValidatorCalloutExtender
+            TargetControlID="valUsername"
+            PopupPosition="PopupPosition.BottomRight"
+            Width="300"
+            CssClass="error-callout"
+            HighlightCssClass="field-with-error" />
+    </div>
+
+    <button type="submit" class="btn btn-primary">Register</button>
+</form>
+
+<style>
+    .error-callout {
+        background-color: #ffebee;
+        border: 1px solid #ef5350;
+        border-radius: 4px;
+        box-shadow: 0 2px 8px rgba(239, 83, 80, 0.2);
+    }
+
+    .field-with-error {
+        background-color: #ffcdd2;
+        border-color: #ef5350;
+    }
+</style>
+
+

Callout with Icons

+
@rendermode InteractiveServer
+
+<form>
+    <div>
+        <label>Password:</label>
+        <TextBox ID="txtPassword" type="password" style="width: 200px;" />
+
+        <RequiredFieldValidator
+            ID="valPassword"
+            ControlToValidate="txtPassword"
+            ErrorMessage="Password is required" />
+
+        <ValidatorCalloutExtender
+            TargetControlID="valPassword"
+            PopupPosition="PopupPosition.TopRight"
+            Width="280"
+            WarningIconImageUrl="~/images/warning-icon.png"
+            CloseImageUrl="~/images/close-icon.png"
+            HighlightCssClass="invalid-field" />
+    </div>
+
+    <button type="submit" class="btn btn-primary">Submit</button>
+</form>
+
+<style>
+    .invalid-field {
+        background-color: #fff3cd;
+        border: 2px solid #ffc107;
+    }
+</style>
+
+

Multiple Validators with Callouts

+
@rendermode InteractiveServer
+
+<form>
+    <div style="margin-bottom: 15px;">
+        <label>First Name:</label>
+        <TextBox ID="txtFirstName" style="width: 200px;" />
+
+        <RequiredFieldValidator
+            ID="valFirstName"
+            ControlToValidate="txtFirstName"
+            ErrorMessage="First name is required" />
+
+        <ValidatorCalloutExtender
+            TargetControlID="valFirstName"
+            PopupPosition="PopupPosition.BottomRight"
+            Width="250" />
+    </div>
+
+    <div style="margin-bottom: 15px;">
+        <label>Email:</label>
+        <TextBox ID="txtEmail2" type="email" style="width: 200px;" />
+
+        <RequiredFieldValidator
+            ID="valEmail2"
+            ControlToValidate="txtEmail2"
+            ErrorMessage="Email is required" />
+
+        <ValidatorCalloutExtender
+            TargetControlID="valEmail2"
+            PopupPosition="PopupPosition.BottomRight"
+            Width="250" />
+    </div>
+
+    <button type="submit" class="btn btn-primary">Submit</button>
+</form>
+
+

HTML Output

+

The ValidatorCalloutExtender creates a styled callout <div> that appears near the validated field when validation fails. The callout includes the validator's error message, optional icon, and optional close button.

+

JavaScript Interop

+

The ValidatorCalloutExtender loads validator-callout-extender.js as an ES module. JavaScript handles:

+
    +
  • Intercepting validator failure events
    • +
  • Creating and positioning the callout popup
    • +
  • Displaying the validator's error message
    • +
  • Applying CSS classes to the invalid field
    • +
  • Displaying warning icon if URL provided
    • +
  • Close button functionality if URL provided
    • +
  • Repositioning callout to stay within viewport
    • +
  • Removing callout when validation passes
    • +
+

Render Mode Requirements

+

The ValidatorCalloutExtender requires InteractiveServer render mode:

+
@rendermode InteractiveServer
+
+

Graceful Degradation

+
    +
  • SSR/Static mode: The extender silently skips initialization. Validator displays inline errors.
    • +
  • JavaScript disabled: Same as SSR — Callout doesn't appear; inline error display is used instead.
    • +
+

Migration Notes

+

From Web Forms Ajax Toolkit

+
    +
  1. +

    Remove ajaxToolkit: prefix + 

    - <ajaxToolkit:ValidatorCalloutExtender
++ <ValidatorCalloutExtender
+

    +
    2. +
  2. +

    Remove runat="server" and ID attributes

    +
    3. +
  3. +

    Use enum types for positions + 

    - PopupPosition="TopRight"
++ PopupPosition="PopupPosition.TopRight"
+

    +
    4. +
+

Before (Web Forms)

+
<asp:TextBox ID="txtEmail" runat="server" />
+
+<asp:RequiredFieldValidator
+    ID="valEmail"
+    ControlToValidate="txtEmail"
+    ErrorMessage="Email is required"
+    runat="server" />
+
+<ajaxToolkit:ValidatorCalloutExtender
+    ID="val1"
+    TargetControlID="valEmail"
+    PopupPosition="TopRight"
+    Width="250"
+    runat="server" />
+
+

After (Blazor)

+
<TextBox ID="txtEmail" />
+
+<RequiredFieldValidator
+    ID="valEmail"
+    ControlToValidate="txtEmail"
+    ErrorMessage="Email is required" />
+
+<ValidatorCalloutExtender
+    TargetControlID="valEmail"
+    PopupPosition="PopupPosition.TopRight"
+    Width="250" />
+
+

Best Practices

+
    +
  1. Keep messages concise — Error messages should be brief but informative
    2. +
  2. Choose position carefully — Avoid positions that would be cut off by viewport edges
    3. +
  3. Use consistent styling — Apply consistent CSS classes across all callouts
    4. +
  4. Provide icons — Warning icons help users quickly identify errors
    5. +
  5. Allow closing — Consider providing a close button with CloseImageUrl
    6. +
  6. Highlight invalid fields — Use HighlightCssClass to make invalid inputs obvious
    7. +
  7. Test viewport positioning — Ensure callouts stay visible in different screen sizes
    8. +
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IssueSolution
Callout not appearingVerify TargetControlID matches the validator's ID. Ensure @rendermode InteractiveServer is set.
Callout positioned off-screenTry a different PopupPosition value (e.g., BottomLeft instead of TopRight).
Icon not showingVerify WarningIconImageUrl points to a valid image file. Check browser console for 404 errors.
Multiple callouts overlapAdjust Width or use different positions for different validators.
Close button not workingEnsure CloseImageUrl points to a valid image and the image is loaded correctly.
+

See Also

+
    +
  • Ajax Control Toolkit Overview — How extenders work and render mode requirements
    • +
  • TextBox Component — The TextBox control
    • +
  • RequiredFieldValidator — Validator control (documentation coming soon)
    • +
  • PasswordStrength — Password feedback extender
    • +
  • Original Ajax Control Toolkit: https://www.asp.net/ajax/ajaxcontroltoolkit
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/index.html b/site/AjaxToolkit/index.html new file mode 100644 index 000000000..7d00945b5 --- /dev/null +++ b/site/AjaxToolkit/index.html @@ -0,0 +1,5731 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Overview - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Ajax Control Toolkit Components

+

The Ajax Control Toolkit in BWFC provides Blazor components that emulate Ajax Control Toolkit extender components, enabling seamless migration of Ajax-enriched Web Forms pages to Blazor with minimal markup changes.

+
+

New to Migration?

+

See the Ajax Toolkit Migration Guide for a comprehensive, step-by-step walkthrough of converting your Ajax Control Toolkit controls to Blazor — including installation, before/after examples for every control, L1 script automation, and troubleshooting.

+
+

What are Extenders?

+

Extenders are special components that attach JavaScript behavior to existing HTML controls without rendering any HTML themselves. They enhance a target control's functionality through client-side JavaScript.

+

Key Characteristics

+
    +
  • Target-based — Extenders identify their target control by TargetControlID
    • +
  • Non-rendering — Extenders produce no HTML output; they only inject behavior
    • +
  • JavaScript-powered — All functionality runs client-side via ES modules
    • +
  • Declarative — Attach to controls with simple Blazor syntax
    • +
  • Familiar API — Same properties and patterns as the original Ajax Control Toolkit
    • +
+

The Migration Advantage

+

Migration from Web Forms is remarkably simple:

+ + + + + + + + + + + + + + + + + + + + + +
Web Forms (Ajax Control Toolkit)BWFC Blazor
<ajaxToolkit:ConfirmButtonExtender><ConfirmButtonExtender>
TargetControlID="btnSubmit"TargetControlID="btnSubmit"
All same propertiesAll same properties
+

You literally just remove the ajaxToolkit: prefix — everything else stays the same!

+

Available Components

+

Accordion

+

A container that displays collapsible content panes arranged vertically. Only one pane is expanded at a time. Includes the companion AccordionPane component.

+

View Documentation →

+

AutoCompleteExtender

+

Provides typeahead/autocomplete functionality for a TextBox. Fetches suggestions via a service URL or Blazor callback and renders a dropdown with keyboard navigation.

+

View Documentation →

+

CalendarExtender

+

Attaches a popup calendar date picker to a TextBox. Supports date formats, navigation views, and date range constraints.

+

View Documentation →

+

CollapsiblePanelExtender

+

Adds collapse/expand functionality to a panel with smooth CSS transitions. Supports separate collapse/expand triggers, dynamic label updates, auto-collapse/expand on hover, and vertical/horizontal animations.

+

View Documentation →

+

ConfirmButtonExtender

+

Displays a browser confirmation dialog when a button is clicked. If the user cancels, the click is suppressed.

+

View Documentation →

+

FilteredTextBoxExtender

+

Restricts input in a TextBox to specified character types. Filters keystrokes in real-time and strips invalid characters on paste.

+

View Documentation →

+

HoverMenuExtender

+

Displays a popup panel when the user hovers over a target control. Supports configurable show/hide delays, positional placement, and hover CSS styling.

+

View Documentation →

+

MaskedEditExtender

+

Applies an input mask to a TextBox, restricting and formatting user input according to a mask pattern. Supports number, date, time, and custom masks.

+

View Documentation →

+

ModalPopupExtender

+

Displays a target element as a modal popup with an overlay backdrop. Supports OK/Cancel actions, focus trapping, drag support, and Escape key dismissal.

+

View Documentation →

+

NumericUpDownExtender

+

Adds numeric up/down spinner buttons to a TextBox. Supports min/max range, step increments, and cycling through a reference value list.

+

View Documentation →

+

PopupControlExtender

+

Attaches a popup panel to a target control, displaying it on click. Lighter than ModalPopupExtender — no overlay, no focus trap.

+

View Documentation →

+

SliderExtender

+

Attaches range slider behavior to a target input. Supports horizontal/vertical orientation, bound control synchronization, and customizable appearance.

+

View Documentation →

+

TabContainer

+

Displays content in tabbed panels with only the active tab visible. Includes the companion TabPanel component for defining each tab.

+

View Documentation →

+

ToggleButtonExtender

+

Replaces a checkbox with a clickable image that toggles between checked and unchecked states. Supports separate images for checked, unchecked, hover, and disabled states.

+

View Documentation →

+

TextBoxWatermarkExtender

+

Displays placeholder/watermark text in a TextBox when it is empty. The watermark disappears when the user focuses or types in the field.

+

View Documentation →

+

DragPanelExtender

+

Makes a panel or container element draggable. Users can click and drag the panel to reposition it on the page, with optional drag handle support.

+

View Documentation →

+

ResizableControlExtender

+

Allows users to resize an element by dragging its edges or a resize handle. Supports minimum and maximum size constraints.

+

View Documentation →

+

DropShadowExtender

+

Adds a drop shadow effect to an element, giving it a raised or floating appearance. Supports customizable opacity, width, and corner rounding.

+

View Documentation →

+

AlwaysVisibleControlExtender

+

Keeps a control visible in a fixed position on the screen even when the user scrolls. Useful for sticky toolbars and persistent navigation.

+

View Documentation →

+

RoundedCornersExtender

+

Applies rounded corners to an element using CSS border-radius. Supports selecting which corners to round and optional background color.

+

View Documentation →

+

UpdatePanelAnimationExtender

+

Provides visual feedback animations when content is updating. Applies CSS classes and fade effects during and after updates.

+

View Documentation →

+

PasswordStrength

+

Displays a visual indicator of password strength as the user types. Evaluates passwords against configurable character requirements.

+

View Documentation →

+

ValidatorCalloutExtender

+

Enhances validators by displaying validation messages in a callout or tooltip bubble instead of inline text.

+

View Documentation →

+

SlideShowExtender

+

Turns an Image control into an automatic slideshow that cycles through images. Supports auto-play, manual navigation, and image titles/descriptions.

+

View Documentation →

+

ListSearchExtender

+

Enables search and filter functionality on a ListBox or DropDownList. As the user types, items are filtered by the search text.

+

View Documentation →

+

BalloonPopupExtender

+

Displays a balloon or tooltip-style popup with a pointer arrow when the user hovers over, focuses on, or clicks a target element.

+

View Documentation →

+

Requirements

+

Render Mode

+

Extender components require InteractiveServer render mode because they depend on JavaScript interoperability.

+
@rendermode InteractiveServer
+
+

JavaScript Support

+

Your application must have IJSRuntime available and be able to execute ES modules. Extenders gracefully degrade in: +- Static Site Generation (SSR) mode without interactivity +- Pre-rendering scenarios

+

When JavaScript isn't available, extenders silently skip initialization (no errors thrown).

+

Usage Pattern

+

All extender components follow this pattern:

+
@* 1. Render the target control (Button, TextBox, etc.) *@
+<Button ID="btnConfirm" Text="Delete" />
+
+@* 2. Attach the extender to the target *@
+<ConfirmButtonExtender 
+    TargetControlID="btnConfirm"
+    ConfirmText="Are you really sure?" />
+
+

Common Properties

+

All extender components inherit these properties from BaseExtenderComponent:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TargetControlIDstring(required)ID of the control to enhance
BehaviorIDstringTargetControlIDOptional behavior identifier for JS lookup
EnabledbooltrueWhether the extender is active
+

Render Mode Considerations

+

InteractiveServer Mode

+

In InteractiveServer render mode, extenders work normally: +- JavaScript initializes automatically after first render +- Parameters can be updated and changes propagate to JavaScript +- Full interoperability available

+

Static/SSR Mode

+

When extenders are placed in Static (non-interactive) components: +- JavaScript interop is not available +- Extenders detect this and skip initialization +- No exceptions are thrown — graceful degradation +- Consider wrapping in an InteractiveServer child component

+ +
@rendermode InteractiveServer
+
+<CascadingAuthenticationState>
+    <Router AppAssembly="@typeof(Program).Assembly">
+        <!-- Your routes here -->
+    </Router>
+</CascadingAuthenticationState>
+
+

Troubleshooting

+

Extender not activating

+
    +
  1. Verify TargetControlID matches the target control's ID attribute
    2. +
  2. Ensure the component is in InteractiveServer render mode
    3. +
  3. Check browser console for JavaScript errors
    4. +
  4. Verify browser allows dynamic module imports
    5. +
+

Target control not found

+
    +
  • Extenders initialize after first render; ensure the target control renders before the extender
    • +
  • JavaScript looks for document.getElementById(TargetControlID)
    • +
  • If target is dynamically created, initialize the extender after the target
    • +
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/AjaxToolkit/migration-guide/index.html b/site/AjaxToolkit/migration-guide/index.html new file mode 100644 index 000000000..0f4f6dcb4 --- /dev/null +++ b/site/AjaxToolkit/migration-guide/index.html @@ -0,0 +1,6801 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Migration Guide - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Ajax Control Toolkit Migration Guide

+

This guide walks you through migrating an ASP.NET Web Forms application that uses the Ajax Control Toolkit to Blazor using BlazorAjaxToolkitComponents (BWFC). The library provides drop-in Blazor replacements for 14 commonly used Ajax Control Toolkit extenders and containers, preserving the same property names, behavior, and rendered HTML so your existing CSS and JavaScript continue to work.

+

Overview

+

What is BlazorAjaxToolkitComponents?

+

BlazorAjaxToolkitComponents is a companion NuGet package to BlazorWebFormsComponents. While the main BWFC package covers standard ASP.NET Web Forms controls (<asp:Button>, <asp:GridView>, etc.), this package covers the Ajax Control Toolkit extenders — the <ajaxToolkit:*> controls that added rich client-side behaviors to Web Forms pages.

+

Why Does It Exist?

+

Many Web Forms applications depend on Ajax Control Toolkit extenders for:

+
    +
  • Confirmation dialogs, input masks, and filtered text boxes
    • +
  • Modal popups, collapsible panels, and hover menus
    • +
  • Tabs, accordions, calendars, and autocomplete
    • +
  • Sliders, numeric spinners, and toggle buttons
    • +
+

Without a migration path for these controls, developers would need to completely rewrite their UI behavior. BlazorAjaxToolkitComponents lets you keep the same markup (minus the ajaxToolkit: prefix) and the same property names, so migration is mechanical rather than creative.

+

Supported Controls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ControlTypeDescription
ConfirmButtonExtenderExtenderConfirmation dialog on button click
FilteredTextBoxExtenderExtenderCharacter filtering for text input
ModalPopupExtenderExtenderModal popup with overlay backdrop
CollapsiblePanelExtenderExtenderCollapsible/expandable panel
Accordion / AccordionPaneContainerVertically stacked collapsible panes
TabContainer / TabPanelContainerTabbed content panels
CalendarExtenderExtenderPopup date picker
AutoCompleteExtenderExtenderTypeahead suggestions
MaskedEditExtenderExtenderInput mask formatting
NumericUpDownExtenderExtenderNumeric spinner buttons
SliderExtenderExtenderRange slider control
ToggleButtonExtenderExtenderImage-based checkbox toggle
PopupControlExtenderExtenderClick-triggered popup panel
HoverMenuExtenderExtenderHover-triggered popup menu
+
+

Installation

+

1. Add the NuGet Package

+
dotnet add package BlazorAjaxToolkitComponents
+
+
+

Note

+

BlazorAjaxToolkitComponents depends on BlazorWebFormsComponents, which will be installed automatically as a transitive dependency.

+
+

2. Add @using Statements to _Imports.razor

+

Add these lines to your project's _Imports.razor file:

+
@using BlazorAjaxToolkitComponents
+@using BlazorAjaxToolkitComponents.Enums
+
+

3. Set Render Mode

+

Ajax Toolkit extender components require InteractiveServer render mode because they depend on JavaScript interoperability. Add this to your App.razor or the pages that use extenders:

+
@rendermode InteractiveServer
+
+

4. JavaScript Interop Setup

+

No manual <script> reference is required. Extender components load their JavaScript modules automatically using ES module imports from the _content/BlazorAjaxToolkitComponents/js/ static assets path. Blazor's static web asset system handles this transparently.

+

Ensure your App.razor or host page includes the standard Blazor script:

+
<script src="_framework/blazor.web.js"></script>
+
+
+

Migration Steps

+

Step 1: Remove ToolkitScriptManager

+

The <ajaxToolkit:ToolkitScriptManager> is not needed in Blazor. Blazor handles script loading and component lifecycle automatically. Simply delete it:

+
- <ajaxToolkit:ToolkitScriptManager ID="ToolkitScriptManager1" runat="server" />
+
+

Step 2: Remove the ajaxToolkit: Prefix

+

All Ajax Control Toolkit controls use the ajaxToolkit: XML namespace prefix. In Blazor, components are referenced by their class name directly:

+
- <ajaxToolkit:ConfirmButtonExtender
++ <ConfirmButtonExtender
+
+

For closing tags:

+
- </ajaxToolkit:Accordion>
++ </Accordion>
+
+

Step 3: Remove runat="server" and Extender ID Attributes

+

Blazor components don't use runat="server". The extender's own ID attribute is also not needed (it was only used for server-side reference in Web Forms):

+
- <ajaxToolkit:ConfirmButtonExtender
+-     ID="cbe1"
+-     runat="server"
++ <ConfirmButtonExtender
+      TargetControlID="btnDelete"
+      ConfirmText="Are you sure?" />
+
+

Step 4: Map Properties (Most Are 1:1)

+

The vast majority of properties keep the same name and type. BWFC was designed for this:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web Forms PropertyBlazor PropertyNotes
TargetControlIDTargetControlIDSame — ID of the target control
ConfirmTextConfirmTextSame
PopupControlIDPopupControlIDSame
BackgroundCssClassBackgroundCssClassSame
Minimum / MaximumMinimum / MaximumSame
FilterTypeFilterTypeSame — uses FilterType enum
MaskMaskSame
HeaderTextHeaderTextSame
+

Enum values are also preserved. For example, FilterType="Numbers" in Web Forms becomes FilterType="FilterType.Numbers" in Blazor (using the C# enum syntax).

+

Step 5: Handle Event Model Differences

+

Web Forms uses server-side event handlers wired up declaratively. Blazor uses EventCallback:

+

Web Forms: +

<ajaxToolkit:TabContainer ID="tabs" runat="server"
+    OnActiveTabChanged="tabs_ActiveTabChanged">
+

+

Blazor: +

<TabContainer ActiveTabIndex="0"
+    OnActiveTabChanged="HandleTabChanged">
+
+@code {
+    void HandleTabChanged(int newIndex)
+    {
+        // Handle tab change
+    }
+}
+

+

Key differences:

+
    +
  • No OnClick wiring on extenders — Extenders attach behavior to their target control. The target control's OnClick (or equivalent) still works normally.
    • +
  • EventCallback instead of server events — Accordion.SelectedIndexChanged is an EventCallback<int>, TabContainer.OnActiveTabChanged is an EventCallback<int>.
    • +
  • Client-side scripts remain strings — Properties like OnOkScript, OnCancelScript, and OnClientActiveTabChanged accept JavaScript code strings, just like in Web Forms.
    • +
+

Step 6: Verify InteractiveServer Render Mode

+

Extender components require JavaScript interop, which is only available in InteractiveServer mode. In Static SSR mode, extenders silently skip initialization (no errors thrown, but no behavior is attached).

+
+

Per-Control Migration Examples

+

ConfirmButtonExtender

+

Displays a browser confirmation dialog when a button is clicked. If cancelled, the click is suppressed.

+
+
+
+
<asp:Button ID="btnDelete" Text="Delete" OnClick="btnDelete_Click" runat="server" />
+
+<ajaxToolkit:ConfirmButtonExtender
+    ID="cbe1"
+    runat="server"
+    TargetControlID="btnDelete"
+    ConfirmText="Are you sure you want to delete this?"
+    ConfirmOnFormSubmit="false" />
+
+
+
+
<Button ID="btnDelete" Text="Delete" OnClick="HandleDelete" />
+
+<ConfirmButtonExtender
+    TargetControlID="btnDelete"
+    ConfirmText="Are you sure you want to delete this?"
+    ConfirmOnFormSubmit="false" />
+
+@code {
+    void HandleDelete() { /* Runs only if user clicks OK */ }
+}
+
+
+
+
+

Properties: TargetControlID, ConfirmText, ConfirmOnFormSubmit, DisplayModalPopupID (reserved), BehaviorID, Enabled

+
+

FilteredTextBoxExtender

+

Restricts input in a TextBox to specified character types, filtering keystrokes in real-time.

+
+
+
+
<asp:TextBox ID="txtPhone" runat="server" />
+
+<ajaxToolkit:FilteredTextBoxExtender
+    ID="fte1"
+    runat="server"
+    TargetControlID="txtPhone"
+    FilterType="Numbers"
+    ValidChars="-+()" />
+
+
+
+
<TextBox ID="txtPhone" />
+
+<FilteredTextBoxExtender
+    TargetControlID="txtPhone"
+    FilterType="FilterType.Numbers"
+    ValidChars="-+()" />
+
+
+
+
+

Properties: TargetControlID, FilterType, ValidChars, InvalidChars, FilterMode, FilterInterval, BehaviorID, Enabled

+
+

Tip

+

Enum values use C# syntax in Blazor: FilterType.Numbers, FilterType.Custom, FilterMode.ValidChars, etc.

+
+
+

ModalPopupExtender

+

Displays a target element as a modal popup with an overlay backdrop. Supports OK/Cancel actions, drag, and drop shadow.

+
+
+
+
<asp:Button ID="btnOpen" Text="Open" runat="server" />
+
+<div ID="myModal" style="display:none; background:white; padding:20px;">
+    <p>Modal content</p>
+    <button ID="btnOK">OK</button>
+    <button ID="btnCancel">Cancel</button>
+</div>
+
+<ajaxToolkit:ModalPopupExtender
+    ID="mpe1"
+    runat="server"
+    TargetControlID="btnOpen"
+    PopupControlID="myModal"
+    BackgroundCssClass="modalBackground"
+    OkControlID="btnOK"
+    CancelControlID="btnCancel"
+    DropShadow="true"
+    Drag="true"
+    PopupDragHandleControlID="dragHandle" />
+
+
+
+
<Button ID="btnOpen" Text="Open" />
+
+<div ID="myModal" style="display:none; background:white; padding:20px;">
+    <p>Modal content</p>
+    <button ID="btnOK">OK</button>
+    <button ID="btnCancel">Cancel</button>
+</div>
+
+<ModalPopupExtender
+    TargetControlID="btnOpen"
+    PopupControlID="myModal"
+    BackgroundCssClass="modalBackground"
+    OkControlID="btnOK"
+    CancelControlID="btnCancel"
+    DropShadow="true"
+    Drag="true"
+    PopupDragHandleControlID="dragHandle" />
+
+
+
+
+

Properties: TargetControlID, PopupControlID, BackgroundCssClass, OkControlID, CancelControlID, OnOkScript, OnCancelScript, DropShadow, Drag, PopupDragHandleControlID, BehaviorID, Enabled

+
+

CollapsiblePanelExtender

+

Adds collapse/expand behavior to a panel with smooth CSS transitions.

+
+
+
+
<asp:Panel ID="pnlContent" runat="server">
+    <p>Collapsible content here</p>
+</asp:Panel>
+
+<asp:Label ID="lblStatus" runat="server" />
+<asp:LinkButton ID="lnkToggle" runat="server" Text="Toggle" />
+
+<ajaxToolkit:CollapsiblePanelExtender
+    ID="cpe1"
+    runat="server"
+    TargetControlID="pnlContent"
+    CollapseControlID="lnkToggle"
+    ExpandControlID="lnkToggle"
+    Collapsed="true"
+    CollapsedText="Show Details"
+    ExpandedText="Hide Details"
+    TextLabelID="lblStatus"
+    ExpandDirection="Vertical"
+    CollapsedSize="0" />
+
+
+
+
<Panel ID="pnlContent">
+    <p>Collapsible content here</p>
+</Panel>
+
+<Label ID="lblStatus" />
+<LinkButton ID="lnkToggle" Text="Toggle" />
+
+<CollapsiblePanelExtender
+    TargetControlID="pnlContent"
+    CollapseControlID="lnkToggle"
+    ExpandControlID="lnkToggle"
+    Collapsed="true"
+    CollapsedText="Show Details"
+    ExpandedText="Hide Details"
+    TextLabelID="lblStatus"
+    ExpandDirection="ExpandDirection.Vertical"
+    CollapsedSize="0" />
+
+
+
+
+

Properties: TargetControlID, CollapseControlID, ExpandControlID, Collapsed, CollapsedSize, ExpandedSize, CollapsedText, ExpandedText, TextLabelID, ExpandDirection, AutoCollapse, AutoExpand, ScrollContents, BehaviorID, Enabled

+
+

Accordion / AccordionPane

+

A container that displays collapsible content panes. Only one pane is expanded at a time.

+
+
+
+
<ajaxToolkit:Accordion ID="acc1" runat="server"
+    SelectedIndex="0"
+    HeaderCssClass="accordionHeader"
+    ContentCssClass="accordionContent"
+    FadeTransitions="true"
+    TransitionDuration="300"
+    RequireOpenedPane="true"
+    SuppressHeaderPostbacks="true">
+    <Panes>
+        <ajaxToolkit:AccordionPane>
+            <Header>Section 1</Header>
+            <Content>
+                <p>Content for section 1</p>
+            </Content>
+        </ajaxToolkit:AccordionPane>
+        <ajaxToolkit:AccordionPane>
+            <Header>Section 2</Header>
+            <Content>
+                <p>Content for section 2</p>
+            </Content>
+        </ajaxToolkit:AccordionPane>
+    </Panes>
+</ajaxToolkit:Accordion>
+
+
+
+
<Accordion
+    SelectedIndex="0"
+    HeaderCssClass="accordionHeader"
+    ContentCssClass="accordionContent"
+    FadeTransitions="true"
+    TransitionDuration="300"
+    RequireOpenedPane="true"
+    SuppressHeaderPostbacks="true"
+    SelectedIndexChanged="HandleSelectionChanged">
+    <AccordionPane>
+        <Header>Section 1</Header>
+        <Content>
+            <p>Content for section 1</p>
+        </Content>
+    </AccordionPane>
+    <AccordionPane>
+        <Header>Section 2</Header>
+        <Content>
+            <p>Content for section 2</p>
+        </Content>
+    </AccordionPane>
+</Accordion>
+
+@code {
+    void HandleSelectionChanged(int index) { /* Handle pane change */ }
+}
+
+
+
+
+
+

Structural Difference

+

In Web Forms, panes are wrapped in a <Panes> collection element. In Blazor, AccordionPane components are placed directly inside Accordion as child content — no <Panes> wrapper needed.

+
+

Accordion Properties: SelectedIndex, SelectedIndexChanged, FadeTransitions, TransitionDuration, HeaderCssClass, ContentCssClass, RequireOpenedPane, AutoSize, SuppressHeaderPostbacks, CssClass

+

AccordionPane Properties: Header (RenderFragment), Content (RenderFragment)

+
+

TabContainer / TabPanel

+

Displays content in tabbed panels with only the active tab visible.

+
+
+
+
<ajaxToolkit:TabContainer ID="tabs1" runat="server"
+    ActiveTabIndex="0"
+    OnClientActiveTabChanged="onTabChanged"
+    CssClass="myTabs">
+    <ajaxToolkit:TabPanel ID="tab1" runat="server"
+        HeaderText="Tab 1">
+        <ContentTemplate>
+            <p>Content for tab 1</p>
+        </ContentTemplate>
+    </ajaxToolkit:TabPanel>
+    <ajaxToolkit:TabPanel ID="tab2" runat="server"
+        HeaderText="Tab 2">
+        <ContentTemplate>
+            <p>Content for tab 2</p>
+        </ContentTemplate>
+    </ajaxToolkit:TabPanel>
+</ajaxToolkit:TabContainer>
+
+
+
+
<TabContainer
+    ActiveTabIndex="0"
+    OnClientActiveTabChanged="onTabChanged"
+    CssClass="myTabs"
+    OnActiveTabChanged="HandleTabChanged">
+    <TabPanel HeaderText="Tab 1">
+        <ContentTemplate>
+            <p>Content for tab 1</p>
+        </ContentTemplate>
+    </TabPanel>
+    <TabPanel HeaderText="Tab 2">
+        <ContentTemplate>
+            <p>Content for tab 2</p>
+        </ContentTemplate>
+    </TabPanel>
+</TabContainer>
+
+@code {
+    void HandleTabChanged(int newIndex) { /* Handle tab change */ }
+}
+
+
+
+
+

TabContainer Properties: ActiveTabIndex, OnActiveTabChanged, OnClientActiveTabChanged, ScrollBars, CssClass

+

TabPanel Properties: HeaderText, HeaderTemplate (RenderFragment), ContentTemplate (RenderFragment), Enabled

+
+

CalendarExtender

+

Attaches a popup calendar date picker to a TextBox.

+
+
+
+
<asp:TextBox ID="txtDate" runat="server" />
+
+<ajaxToolkit:CalendarExtender
+    ID="ce1"
+    runat="server"
+    TargetControlID="txtDate"
+    Format="MM/dd/yyyy"
+    PopupPosition="BottomLeft"
+    StartDate="2024-01-01"
+    EndDate="2025-12-31"
+    CssClass="calendarPopup" />
+
+
+
+
<TextBox ID="txtDate" />
+
+<CalendarExtender
+    TargetControlID="txtDate"
+    Format="MM/dd/yyyy"
+    PopupPosition="CalendarPosition.BottomLeft"
+    StartDate="@(new DateTime(2024, 1, 1))"
+    EndDate="@(new DateTime(2025, 12, 31))"
+    CssClass="calendarPopup" />
+
+
+
+
+

Properties: TargetControlID, Format, PopupPosition, DefaultView, StartDate, EndDate, SelectedDate, TodaysDate, CssClass, OnClientDateSelectionChanged, BehaviorID, Enabled

+
+

Tip

+

Date properties (StartDate, EndDate, SelectedDate, TodaysDate) are DateTime? in Blazor. Use C# expressions like @(new DateTime(2024, 1, 1)) instead of string literals.

+
+
+

AutoCompleteExtender

+

Provides typeahead/autocomplete functionality for a TextBox.

+
+
+
+
<asp:TextBox ID="txtSearch" runat="server" />
+
+<ajaxToolkit:AutoCompleteExtender
+    ID="ace1"
+    runat="server"
+    TargetControlID="txtSearch"
+    ServicePath="~/AutoCompleteService.asmx"
+    ServiceMethod="GetCompletionList"
+    MinimumPrefixLength="2"
+    CompletionSetCount="10"
+    CompletionInterval="500"
+    CompletionListCssClass="autocomplete-list"
+    CompletionListItemCssClass="autocomplete-item"
+    CompletionListHighlightedItemCssClass="autocomplete-highlight"
+    FirstRowSelected="true" />
+
+
+
+
<TextBox ID="txtSearch" />
+
+<AutoCompleteExtender
+    TargetControlID="txtSearch"
+    ServicePath="/api/autocomplete"
+    ServiceMethod="GetCompletionList"
+    MinimumPrefixLength="2"
+    CompletionSetCount="10"
+    CompletionInterval="500"
+    CompletionListCssClass="autocomplete-list"
+    CompletionListItemCssClass="autocomplete-item"
+    CompletionListHighlightedItemCssClass="autocomplete-highlight"
+    FirstRowSelected="true"
+    CompletionDataRequested="HandleCompletionRequest" />
+
+@code {
+    async Task HandleCompletionRequest(string prefix)
+    {
+        // Fetch suggestions server-side
+    }
+}
+
+
+
+
+

Properties: TargetControlID, ServicePath, ServiceMethod, MinimumPrefixLength, CompletionSetCount, CompletionInterval, CompletionListCssClass, CompletionListItemCssClass, CompletionListHighlightedItemCssClass, DelimiterCharacters, FirstRowSelected, ShowOnlyCurrentWordInCompletionListItem, OnClientItemSelected, OnClientPopulating, OnClientPopulated, CompletionDataRequested, BehaviorID, Enabled

+
+

Note

+

The Blazor version adds CompletionDataRequested — an EventCallback<string> for fetching suggestions server-side, replacing the Web Forms ASMX service pattern.

+
+
+

MaskedEditExtender

+

Applies an input mask to a TextBox, formatting user input according to a pattern.

+
+
+
+
<asp:TextBox ID="txtPhone" runat="server" />
+
+<ajaxToolkit:MaskedEditExtender
+    ID="mee1"
+    runat="server"
+    TargetControlID="txtPhone"
+    Mask="(999) 999-9999"
+    MaskType="Number"
+    InputDirection="LeftToRight"
+    ClearMaskOnLostFocus="true"
+    PromptCharacter="_" />
+
+
+
+
<TextBox ID="txtPhone" />
+
+<MaskedEditExtender
+    TargetControlID="txtPhone"
+    Mask="(999) 999-9999"
+    MaskType="MaskType.Number"
+    InputDirection="InputDirection.LeftToRight"
+    ClearMaskOnLostFocus="true"
+    PromptCharacter="_" />
+
+
+
+
+

Properties: TargetControlID, Mask, MaskType, InputDirection, PromptCharacter, AutoComplete, AutoCompleteValue, Filtered, ClearMaskOnLostFocus, ClearTextOnInvalid, AcceptAMPM, AcceptNegative, ErrorTooltipEnabled, ErrorTooltipCssClass, BehaviorID, Enabled

+
+

NumericUpDownExtender

+

Adds numeric up/down spinner buttons to a TextBox.

+
+
+
+
<asp:TextBox ID="txtQuantity" runat="server" Text="1" />
+
+<ajaxToolkit:NumericUpDownExtender
+    ID="nud1"
+    runat="server"
+    TargetControlID="txtQuantity"
+    Width="120"
+    Minimum="1"
+    Maximum="100"
+    Step="1" />
+
+
+
+
<TextBox ID="txtQuantity" Text="1" />
+
+<NumericUpDownExtender
+    TargetControlID="txtQuantity"
+    Width="120"
+    Minimum="1"
+    Maximum="100"
+    Step="1" />
+
+
+
+
+

Properties: TargetControlID, Width, Minimum, Maximum, Step, RefValues, ServiceUpPath, ServiceUpMethod, ServiceDownPath, ServiceDownMethod, Tag, BehaviorID, Enabled

+
+

SliderExtender

+

Attaches range slider behavior to a target input element.

+
+
+
+
<asp:TextBox ID="txtSlider" runat="server" />
+<asp:Label ID="lblValue" runat="server" />
+
+<ajaxToolkit:SliderExtender
+    ID="se1"
+    runat="server"
+    TargetControlID="txtSlider"
+    BoundControlID="lblValue"
+    Minimum="0"
+    Maximum="100"
+    Steps="10"
+    Orientation="Horizontal"
+    RailCssClass="sliderRail"
+    HandleCssClass="sliderHandle"
+    TooltipText="Value: {0}" />
+
+
+
+
<TextBox ID="txtSlider" />
+<Label ID="lblValue" />
+
+<SliderExtender
+    TargetControlID="txtSlider"
+    BoundControlID="lblValue"
+    Minimum="0"
+    Maximum="100"
+    Steps="10"
+    Orientation="SliderOrientation.Horizontal"
+    RailCssClass="sliderRail"
+    HandleCssClass="sliderHandle"
+    TooltipText="Value: {0}" />
+
+
+
+
+

Properties: TargetControlID, Minimum, Maximum, Steps, Value, BoundControlID, Orientation, RailCssClass, HandleCssClass, HandleImageUrl, Length, Decimals, TooltipText, BehaviorID, Enabled

+
+

ToggleButtonExtender

+

Replaces a checkbox with a clickable image that toggles between checked and unchecked states.

+
+
+
+
<asp:CheckBox ID="chkAgree" runat="server" />
+
+<ajaxToolkit:ToggleButtonExtender
+    ID="tbe1"
+    runat="server"
+    TargetControlID="chkAgree"
+    ImageWidth="24"
+    ImageHeight="24"
+    UncheckedImageUrl="~/images/unchecked.png"
+    CheckedImageUrl="~/images/checked.png"
+    UncheckedImageAlternateText="Not agreed"
+    CheckedImageAlternateText="Agreed"
+    CheckedImageOverUrl="~/images/checked-hover.png"
+    UncheckedImageOverUrl="~/images/unchecked-hover.png" />
+
+
+
+
<CheckBox ID="chkAgree" />
+
+<ToggleButtonExtender
+    TargetControlID="chkAgree"
+    ImageWidth="24"
+    ImageHeight="24"
+    UncheckedImageUrl="images/unchecked.png"
+    CheckedImageUrl="images/checked.png"
+    UncheckedImageAlternateText="Not agreed"
+    CheckedImageAlternateText="Agreed"
+    CheckedImageOverUrl="images/checked-hover.png"
+    UncheckedImageOverUrl="images/unchecked-hover.png" />
+
+
+
+
+

Properties: TargetControlID, ImageWidth, ImageHeight, UncheckedImageUrl, CheckedImageUrl, UncheckedImageAlternateText, CheckedImageAlternateText, CheckedImageOverUrl, UncheckedImageOverUrl, DisabledUncheckedImageUrl, DisabledCheckedImageUrl, BehaviorID, Enabled

+
+

Tip

+

Replace ~/ paths with relative paths in Blazor. Static assets go in wwwroot/.

+
+
+

PopupControlExtender

+

Attaches a popup panel to a target control, displaying it on click. Lighter than ModalPopupExtender — no overlay or focus trap.

+
+
+
+
<asp:TextBox ID="txtColor" runat="server" />
+
+<asp:Panel ID="pnlColorPicker" runat="server" style="display:none;">
+    <!-- Color picker content -->
+</asp:Panel>
+
+<ajaxToolkit:PopupControlExtender
+    ID="pce1"
+    runat="server"
+    TargetControlID="txtColor"
+    PopupControlID="pnlColorPicker"
+    Position="Bottom"
+    OffsetX="0"
+    OffsetY="2"
+    CommitProperty="value"
+    CommitScript="onColorSelected()" />
+
+
+
+
<TextBox ID="txtColor" />
+
+<Panel ID="pnlColorPicker" style="display:none;">
+    @* Color picker content *@
+</Panel>
+
+<PopupControlExtender
+    TargetControlID="txtColor"
+    PopupControlID="pnlColorPicker"
+    Position="PopupPosition.Bottom"
+    OffsetX="0"
+    OffsetY="2"
+    CommitProperty="value"
+    CommitScript="onColorSelected()" />
+
+
+
+
+

Properties: TargetControlID, PopupControlID, Position, OffsetX, OffsetY, CommitProperty, CommitScript, ExtenderControlID, BehaviorID, Enabled

+
+

HoverMenuExtender

+

Displays a popup panel when the user hovers over a target control.

+
+
+
+
<asp:Label ID="lblItem" runat="server" Text="Hover over me" />
+
+<asp:Panel ID="pnlMenu" runat="server" CssClass="hoverMenu" style="display:none;">
+    <a href="#">Edit</a>
+    <a href="#">Delete</a>
+</asp:Panel>
+
+<ajaxToolkit:HoverMenuExtender
+    ID="hme1"
+    runat="server"
+    TargetControlID="lblItem"
+    PopupControlID="pnlMenu"
+    PopupPosition="Right"
+    OffsetX="5"
+    OffsetY="0"
+    PopDelay="200"
+    HoverDelay="500"
+    HoverCssClass="hoverHighlight" />
+
+
+
+
<Label ID="lblItem" Text="Hover over me" />
+
+<Panel ID="pnlMenu" CssClass="hoverMenu" style="display:none;">
+    <a href="#">Edit</a>
+    <a href="#">Delete</a>
+</Panel>
+
+<HoverMenuExtender
+    TargetControlID="lblItem"
+    PopupControlID="pnlMenu"
+    PopupPosition="PopupPosition.Right"
+    OffsetX="5"
+    OffsetY="0"
+    PopDelay="200"
+    HoverDelay="500"
+    HoverCssClass="hoverHighlight" />
+
+
+
+
+

Properties: TargetControlID, PopupControlID, PopupPosition, OffsetX, OffsetY, PopDelay, HoverDelay, HoverCssClass, BehaviorID, Enabled

+
+

L1 Script Support

+

The bwfc-migrate.ps1 script (located in migration-toolkit/scripts/) automates much of the Ajax Control Toolkit conversion as part of the L1 (Level 1) mechanical migration pass.

+

What the Script Handles Automatically

+
    +
  1. +

    Removes <ajaxToolkit:ToolkitScriptManager> — Both self-closing and block forms are stripped entirely since Blazor doesn't need them.

    +
    2. +
  2. +

    Converts known ajaxToolkit: prefixes — For all 16 supported components (the 14 controls listed above plus their companion types), the script strips the ajaxToolkit: prefix from both opening and closing tags:

    +
      +
    • <ajaxToolkit:Accordion> → <Accordion>
      • +
    • </ajaxToolkit:AccordionPane> → </AccordionPane>
      • +
    +
    3. +
  3. +

    Flags unrecognized controls — Any ajaxToolkit: control not in the known list is replaced with a TODO comment: + 

    @* TODO: Convert ajaxToolkit:RatingExtender — no BWFC equivalent yet *@
+

    +
    4. +
  4. +

    Adds @using statements — When Ajax Toolkit controls are detected, the script ensures @using BlazorAjaxToolkitComponents is added to _Imports.razor.

    +
    5. +
+

Running the Script

+
.\migration-toolkit\scripts\bwfc-migrate.ps1 -SourcePath "C:\MyWebFormsApp" -OutputPath "C:\MyBlazorApp"
+
+

What Requires Manual Follow-up (L2)

+

After the L1 script runs, you may need to:

+
    +
  • Convert enum string values to C# enum syntax (e.g., FilterType="Numbers" → FilterType="FilterType.Numbers")
    • +
  • Replace ~/ asset paths with relative Blazor paths
    • +
  • Convert server-side event handlers to EventCallback syntax
    • +
  • Remove the <Panes> wrapper from Accordion content
    • +
  • Verify TargetControlID references match the migrated control IDs
    • +
  • Set @rendermode InteractiveServer on pages that use extenders
    • +
+
+

Common Issues & Troubleshooting

+

Extender not activating

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SymptomCauseSolution
No behavior on button clickMissing render modeAdd @rendermode InteractiveServer to the page
Extender initializes but no effectWrong TargetControlIDVerify the ID matches the target control's ID attribute exactly (case-sensitive)
JS console error on importMissing static assetsEnsure BlazorAjaxToolkitComponents NuGet package is installed and project is built
Works in dev, fails in productionStatic asset path issueVerify _content/BlazorAjaxToolkitComponents/ is being served
+

Enum values not recognized

+

Blazor requires C# enum syntax. String values from Web Forms markup need conversion:

+
- FilterType="Numbers"
++ FilterType="FilterType.Numbers"
+
+- MaskType="Number"
++ MaskType="MaskType.Number"
+
+- Orientation="Horizontal"
++ Orientation="SliderOrientation.Horizontal"
+
+

TargetControlID not found at runtime

+
    +
  • Ensure the target control renders before the extender in the component tree
    • +
  • JavaScript resolves the target via document.getElementById() — the element must exist in the DOM
    • +
  • If the target is inside a conditional @if block, the extender may initialize before the target renders
    • +
+

Accordion panes not rendering

+
    +
  • Remove the <Panes> wrapper — Blazor uses direct child content
    • +
  • Ensure each AccordionPane is a direct child of Accordion
    • +
  • Check that Header and Content render fragments are present
    • +
+ +
    +
  • Verify OkControlID and CancelControlID match the button ID attributes inside the modal
    • +
  • Ensure buttons are inside the PopupControlID element
    • +
  • Check that the popup element has style="display:none;" initially
    • +
+

Calendar dates as strings

+

Date properties are DateTime? in Blazor, not strings:

+
- StartDate="2024-01-01"
++ StartDate="@(new DateTime(2024, 1, 1))"
+
+

Static SSR mode — extenders don't work

+

Extenders require JavaScript interop which is only available in InteractiveServer mode. In Static SSR, extenders silently skip initialization. Wrap extender usage in an interactive component:

+
@rendermode InteractiveServer
+
+@* All extenders on this page will work *@
+
+
+

Feature Comparison Table

+

The table below shows which Ajax Control Toolkit features are supported in BlazorAjaxToolkitComponents.

+

Legend

+ + + + + + + + + + + + + + + + + + + + + + + + + +
StatusMeaning
✅ SupportedFully implemented with same behavior
⚠️ PartialImplemented with limitations — see notes
🔮 PlannedNot yet implemented — reserved for future versions
❌ Not PlannedWill not be implemented
+

Control Support Matrix

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Ajax Control Toolkit ControlBWFC StatusNotes
ConfirmButtonExtender✅ SupportedDisplayModalPopupID reserved for future use
FilteredTextBoxExtender✅ SupportedAll filter types and modes supported
ModalPopupExtender✅ SupportedFull support including drag, drop shadow, focus trap
CollapsiblePanelExtender✅ SupportedVertical and horizontal expand directions
Accordion✅ SupportedIncludes JS animation support
AccordionPane✅ SupportedDirect child content (no <Panes> wrapper)
TabContainer✅ SupportedClient callback, scrollbar support
TabPanel✅ SupportedHeaderText, HeaderTemplate, and Enabled
CalendarExtender✅ SupportedDate ranges, views, and format strings
AutoCompleteExtender✅ SupportedAdds CompletionDataRequested EventCallback
MaskedEditExtender✅ SupportedAll mask types and input directions
NumericUpDownExtender✅ SupportedStep, range, and reference values
SliderExtender✅ SupportedHorizontal/vertical, bound control sync
ToggleButtonExtender✅ SupportedAll image states including disabled
PopupControlExtender✅ SupportedPositional placement and commit support
HoverMenuExtender✅ SupportedShow/hide delays and hover CSS class
ToolkitScriptManager❌ Not PlannedNot needed — Blazor handles script loading
AlwaysVisibleControlExtender🔮 Planned—
AnimationExtender🔮 Planned—
CascadingDropDown🔮 Planned—
ColorPickerExtender🔮 Planned—
DragPanelExtender🔮 Planned—
DropDownExtender🔮 Planned—
DropShadowExtender🔮 Planned—
DynamicPopulateExtender🔮 Planned—
ListSearchExtender🔮 Planned—
MutuallyExclusiveCheckBoxExtender🔮 Planned—
PagingBulletedListExtender🔮 Planned—
PasswordStrength🔮 Planned—
Rating🔮 Planned—
ReorderList🔮 Planned—
ResizableControlExtender🔮 Planned—
RoundedCornersExtender🔮 Planned—
TextBoxWatermarkExtender🔮 Planned—
UpdatePanelAnimationExtender🔮 Planned—
ValidatorCalloutExtender🔮 Planned—
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/Chart/index.html b/site/DataControls/Chart/index.html new file mode 100644 index 000000000..a6886170e --- /dev/null +++ b/site/DataControls/Chart/index.html @@ -0,0 +1,6008 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Chart - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Chart

+

The Chart component provides data visualization by rendering interactive charts in Blazor, emulating the ASP.NET Web Forms Chart control. This is the first component in the library to use JavaScript interop, powered by Chart.js for client-side rendering.

+

Original Microsoft documentation: System.Web.UI.DataVisualization.Charting.Chart

+
+

HTML Output Exception

+

The Web Forms Chart control renders an <img src="/ChartImg.axd?..."> tag — a server-generated raster image. The Blazor Chart component renders a <canvas> element powered by Chart.js. This is a justified deviation from the project's identical-HTML-output rule because:

+
    +
  • Vector vs. raster: Canvas-based charts scale crisply at any resolution; the old <img> approach produced fixed-resolution PNGs/JPEGs
    • +
  • Interactive vs. static: Chart.js supports tooltips, hover effects, and animations out of the box — Web Forms charts were static images
    • +
  • Client-side rendering: No server round-trip to generate chart images, resulting in better performance
    • +
  • No server dependency: Web Forms required the ChartImg.axd HTTP handler and System.Web.DataVisualization assembly on the server
    • +
+

Any CSS that targeted img inside your chart container will need to target canvas instead.

+
+
+

Chart.js Dependency

+

The Chart component automatically loads Chart.js via JavaScript interop. The chart.min.js file is bundled in the library's static assets and loaded on demand — no manual script tags are required. See JavaScript Setup for general JS configuration options.

+
+

Features Supported in Blazor

+

Chart Types (8 of 35)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SeriesChartTypeChart.js MappingDescription
Columnbar (vertical)Vertical bar chart
Barbar (horizontal)Horizontal bar chart
LinelineLine chart
Arealine (with fill)Filled area chart
PiepiePie chart
DoughnutdoughnutDoughnut (ring) chart
PointscatterScatter plot
StackedColumnbar (stacked)Stacked vertical bar chart
+

Component Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
ChartWidthstringWidth in CSS units (e.g., "400px", "100%")
ChartHeightstringHeight in CSS units (e.g., "300px")
PaletteChartPaletteColor palette for auto-coloring series (default: BrightPastel)
ImageTypestringAPI compatibility only; not functional in Blazor
IDstringHTML element ID
CssClassstringCSS class applied to the container <div>
StylestringInline CSS style
VisibleboolWhether the chart is rendered
+

Child Components

+
    +
  • ChartSeries — Defines a data series (chart type, data points, data binding fields)
    • +
  • ChartArea — Configures chart area with X/Y axis settings
    • +
  • ChartLegend — Adds and configures a chart legend
    • +
  • ChartTitle — Adds a chart title
    • +
+

ChartSeries Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
NamestringSeries label shown in the legend
ChartTypeSeriesChartTypeChart type for this series
ChartAreastringName of the chart area this series belongs to
XValueMemberstringField name for X values when data-binding
YValueMembersstringField name(s) for Y values when data-binding
ColorWebColorSeries color override
BorderWidthintBorder/line width
IsVisibleInLegendboolWhether this series appears in the legend (default: true)
LegendstringName of the legend this series is associated with
MarkerStylestringMarker style for data points
ToolTipstringTooltip text
PointsList<DataPoint>Manual data points
ItemsIEnumerable<object>Data source items for data-binding
+

DataPoint Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
XValueobjectX-axis value
YValuesdouble[]Y-axis values
LabelstringDisplay label
ColorWebColorPer-point color override
ToolTipstringTooltip text
IsValueShownAsLabelboolShow value as a label on the chart
+

ChartArea Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
NamestringUnique name of the chart area
AreaBackColorWebColorBackground color
AxisXAxisX-axis configuration
AxisYAxisY-axis configuration
+

Axis Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
TitlestringAxis title text
Minimumdouble?Minimum axis value
Maximumdouble?Maximum axis value
Intervaldouble?Tick interval (step size)
IsLogarithmicboolUse logarithmic scale
+

ChartLegend Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
NamestringUnique name
LegendDockingDocking?Position: Top, Bottom, Left, Right
AlignmentstringLegend alignment
TitlestringLegend title text
+

ChartTitle Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
TextstringTitle text
AlignmentstringTitle alignment
TitleDockingDocking?Position: Top, Bottom, Left, Right
+

Chart Palettes

+

12 built-in color palettes matching the Web Forms ChartColorPalette enum:

+

None, BrightPastel (default), Berry, Chocolate, EarthTones, Excel, Fire, Grayscale, Light, Pastel, SeaGreen, SemiTransparent

+ +

Below is a visual reference for each of the 8 supported chart types. Use this gallery to choose the right chart type for your data and to see what the Blazor Chart component produces.

+

Column

+

Column Chart

+

Enum value: SeriesChartType.Column

+

The classic vertical bar chart — ideal for comparing discrete categories side by side. Use this when your X-axis represents categories (months, products, regions) and you want to emphasize differences in magnitude. This is the most commonly used chart type in Web Forms applications.

+

Line

+

Line Chart

+

Enum value: SeriesChartType.Line

+

Connects data points with straight line segments, perfect for showing trends over time. Use this when your X-axis represents a continuous or sequential dimension (dates, quarters, versions) and you want to highlight the direction and rate of change. Supports multiple series for comparison.

+

Bar

+

Bar Chart

+

Enum value: SeriesChartType.Bar

+

A horizontal bar chart — the same concept as Column but rotated 90°. Use this when your category labels are long (e.g., product names, department titles) or when you have many categories that would crowd a vertical axis.

+

Pie

+

Pie Chart

+

Enum value: SeriesChartType.Pie

+

Displays proportions of a whole as slices of a circle. Use this when you have a single data series and want to show each category's percentage of the total. Best with 3–7 slices — more than that becomes hard to read. Each slice is automatically assigned a distinct color from the active palette.

+

Doughnut

+

Doughnut Chart

+

Enum value: SeriesChartType.Doughnut

+

A ring-shaped variant of the Pie chart with a hollow center. Use this when you want the same part-to-whole visualization as a Pie chart but prefer a cleaner look, or when you want to place a summary value or label in the center area. Each segment receives a distinct palette color automatically.

+

Area

+

Area Chart

+

Enum value: SeriesChartType.Area

+

A Line chart with the region below the line filled in. Use this when you want to emphasize the volume or cumulative total over time, rather than just the trend line. Works well for showing how a value accumulates or for comparing the magnitude of multiple series.

+

Scatter

+

Scatter Chart

+

Enum value: SeriesChartType.Point

+

Plots individual data points on an X/Y grid without connecting lines. Use this when both axes represent numeric values and you want to reveal correlations, clusters, or outliers in your data. Note that the Web Forms enum value is Point, not Scatter.

+

Stacked Column

+

Stacked Column Chart

+

Enum value: SeriesChartType.StackedColumn

+

Stacks multiple series vertically within each category column. Use this when you want to show both the total value per category and the breakdown of contributing series. Each color band represents one series, and the full column height shows the aggregate.

+

Web Forms Features NOT Supported

+

Chart Types Not Supported

+

27 additional chart types from the SeriesChartType enum are defined but will throw NotSupportedException if used. The most commonly requested:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Chart TypeStatusNotes
StockNot supportedOHLC financial charts
CandlestickNot supportedFinancial candlestick charts
BubbleNot supportedBubble charts (sized scatter)
RadarNot supportedRadar/spider charts
PolarNot supportedPolar area charts
FunnelNot supportedFunnel charts
PyramidNot supportedPyramid charts
SplineNot supportedSmooth line charts
StackedBarNot supportedStacked horizontal bars
StackedAreaNot supportedStacked area charts
Range / RangeColumnNot supportedRange charts
BoxPlotNot supportedStatistical box plots
+

Other Unsupported Features

+
    +
  • Image export (SaveImage) — Not available. Use the Chart.js canvas API directly via JS: canvas.toDataURL() or canvas.toBlob()
    • +
  • 3D chart rendering — Chart.js is 2D only; Web Forms supported ChartArea3DStyle
    • +
  • Annotations — Web Forms Annotations collection is not implemented
    • +
  • Map areas / hot spots — Clickable regions on the chart image (MapAreas) are not supported
    • +
  • Data binding via DataSource / DataBind() — Use the Items parameter on ChartSeries or populate Points manually
    • +
  • ChartImg.axd HTTP handler — Not needed; rendering is client-side
    • +
  • Skins and themes — Use CSS and Palette instead
    • +
  • Serialization (ChartSerializer) — Not applicable
    • +
+

Syntax Comparison

+
+
+
+
<asp:Chart
+    ID="Chart1"
+    runat="server"
+    Width="600px"
+    Height="400px"
+    Palette="BrightPastel"
+    ImageType="Png"
+>
+    <Titles>
+        <asp:Title Text="Monthly Sales" Docking="Top" />
+    </Titles>
+    <Legends>
+        <asp:Legend Name="Legend1" Docking="Bottom" />
+    </Legends>
+    <Series>
+        <asp:Series
+            Name="Sales"
+            ChartType="Column"
+            XValueMember="Month"
+            YValueMembers="Amount"
+        />
+    </Series>
+    <ChartAreas>
+        <asp:ChartArea Name="ChartArea1">
+            <AxisX Title="Month" />
+            <AxisY Title="Revenue ($)" />
+        </asp:ChartArea>
+    </ChartAreas>
+</asp:Chart>
+
+

Code-behind:

+
protected void Page_Load(object sender, EventArgs e)
+{
+    Chart1.DataSource = GetSalesData();
+    Chart1.DataBind();
+}
+
+
+
+
<Chart ID="Chart1" ChartWidth="600px" ChartHeight="400px" Palette="ChartPalette.BrightPastel">
+    <ChartTitle Text="Monthly Sales" />
+    <ChartLegend Name="Legend1" LegendDocking="Docking.Bottom" />
+    <ChartSeries Name="Sales" ChartType="SeriesChartType.Column"
+                 Points="@salesData" />
+    <ChartArea Name="ChartArea1"
+               AxisX="@(new Axis { Title = "Month" })"
+               AxisY="@(new Axis { Title = "Revenue ($)" })" />
+</Chart>
+
+@code {
+    private List<DataPoint> salesData = new()
+    {
+        new DataPoint { Label = "Jan", YValues = new[] { 12000.0 } },
+        new DataPoint { Label = "Feb", YValues = new[] { 15000.0 } },
+        new DataPoint { Label = "Mar", YValues = new[] { 18000.0 } },
+        new DataPoint { Label = "Apr", YValues = new[] { 14000.0 } },
+        new DataPoint { Label = "May", YValues = new[] { 21000.0 } },
+        new DataPoint { Label = "Jun", YValues = new[] { 19000.0 } }
+    };
+}
+
+
+
+
+

Examples

+

Data-Bound Chart

+
<Chart ID="SalesChart" ChartWidth="100%" ChartHeight="400px">
+    <ChartTitle Text="Sales by Region" />
+    <ChartSeries Name="Revenue" ChartType="SeriesChartType.Column"
+                 XValueMember="Region" YValueMembers="Revenue"
+                 Items="@regions" />
+    <ChartArea Name="MainArea"
+               AxisX="@(new Axis { Title = "Region" })"
+               AxisY="@(new Axis { Title = "Revenue ($)", Minimum = 0 })" />
+</Chart>
+
+@code {
+    private List<object> regions = new()
+    {
+        new { Region = "North", Revenue = 45000 },
+        new { Region = "South", Revenue = 38000 },
+        new { Region = "East", Revenue = 52000 },
+        new { Region = "West", Revenue = 41000 }
+    };
+}
+
+

Multi-Series Line Chart

+
<Chart ID="TrendChart" ChartWidth="700px" ChartHeight="400px"
+       Palette="ChartPalette.Excel">
+    <ChartTitle Text="Quarterly Trends" TitleDocking="Docking.Top" />
+    <ChartLegend Name="Legend1" LegendDocking="Docking.Bottom" />
+    <ChartSeries Name="2024" ChartType="SeriesChartType.Line"
+                 Points="@data2024" BorderWidth="2" />
+    <ChartSeries Name="2025" ChartType="SeriesChartType.Line"
+                 Points="@data2025" BorderWidth="2" />
+    <ChartArea Name="ChartArea1"
+               AxisX="@(new Axis { Title = "Quarter" })"
+               AxisY="@(new Axis { Title = "Units Sold", Minimum = 0 })" />
+</Chart>
+
+@code {
+    private List<DataPoint> data2024 = new()
+    {
+        new DataPoint { Label = "Q1", YValues = new[] { 120.0 } },
+        new DataPoint { Label = "Q2", YValues = new[] { 150.0 } },
+        new DataPoint { Label = "Q3", YValues = new[] { 180.0 } },
+        new DataPoint { Label = "Q4", YValues = new[] { 200.0 } }
+    };
+
+    private List<DataPoint> data2025 = new()
+    {
+        new DataPoint { Label = "Q1", YValues = new[] { 140.0 } },
+        new DataPoint { Label = "Q2", YValues = new[] { 175.0 } },
+        new DataPoint { Label = "Q3", YValues = new[] { 210.0 } },
+        new DataPoint { Label = "Q4", YValues = new[] { 245.0 } }
+    };
+}
+
+

Pie Chart with Legend

+
<Chart ID="PieChart" ChartWidth="500px" ChartHeight="400px"
+       Palette="ChartPalette.Berry">
+    <ChartTitle Text="Market Share" />
+    <ChartLegend Name="Legend1" LegendDocking="Docking.Right"
+                 Title="Products" />
+    <ChartSeries Name="Share" ChartType="SeriesChartType.Pie"
+                 Points="@marketData" />
+</Chart>
+
+@code {
+    private List<DataPoint> marketData = new()
+    {
+        new DataPoint { Label = "Product A", YValues = new[] { 35.0 } },
+        new DataPoint { Label = "Product B", YValues = new[] { 28.0 } },
+        new DataPoint { Label = "Product C", YValues = new[] { 22.0 } },
+        new DataPoint { Label = "Product D", YValues = new[] { 15.0 } }
+    };
+}
+
+

HTML Output

+

Blazor Input

+
<Chart ID="MyChart" ChartWidth="400px" ChartHeight="300px">
+    <ChartSeries Name="Sales" ChartType="SeriesChartType.Column"
+                 Points="@data" />
+</Chart>
+
+

Rendered HTML

+
<div id="MyChart" style="width:400px;height:300px">
+    <canvas id="MyChart_canvas_a1b2c3d4"></canvas>
+</div>
+
+
+

Comparison with Web Forms Output

+

Web Forms rendered: <img src="/ChartImg.axd?i=chart_abc123&amp;g=..." />

+

The Blazor component renders a <div> wrapper with a <canvas> child. Chart.js draws directly on the canvas — no server-generated images, no HTTP handler.

+
+

Migration Notes

+
    +
  1. Remove the asp: prefix — <asp:Chart> becomes <Chart>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Replace DataSource + DataBind() with Items parameter — Pass your data collection to ChartSeries.Items or populate ChartSeries.Points manually
    4. +
  4. ChartType values remain the same — Column, Bar, Line, Pie, etc. are identical enum values (use SeriesChartType.Column syntax)
    5. +
  5. Palette values remain the same — Use ChartPalette.BrightPastel syntax instead of the string "BrightPastel"
    6. +
  6. Chart.js renders client-side — No ChartImg.axd handler registration needed; better performance and interactivity
    7. +
  7. Width/Height become ChartWidth/ChartHeight — These accept CSS unit strings (e.g., "400px", "100%")
    8. +
  8. Axis configuration uses POCO objects — Instead of nested XML elements, use new Axis { Title = "...", Minimum = 0 }
    9. +
  9. Child element names changed — <Titles> → <ChartTitle>, <Legends> → <ChartLegend>, <Series> → <ChartSeries>, <ChartAreas> → <ChartArea> (singular, no wrapper element)
    10. +
  10. ImageType is ignored — Chart.js renders to canvas, not an image file
    11. +
+
+
+
+
<asp:Chart ID="Chart1" runat="server" Width="600" Height="400"
+           Palette="BrightPastel" ImageType="Png">
+    <Titles>
+        <asp:Title Text="Sales Report" Docking="Top" />
+    </Titles>
+    <Legends>
+        <asp:Legend Name="Legend1" Docking="Bottom" />
+    </Legends>
+    <Series>
+        <asp:Series Name="Revenue" ChartType="Column"
+                    XValueMember="Month" YValueMembers="Amount" />
+    </Series>
+    <ChartAreas>
+        <asp:ChartArea Name="ChartArea1">
+            <AxisX Title="Month" />
+            <AxisY Title="Amount ($)" />
+        </asp:ChartArea>
+    </ChartAreas>
+</asp:Chart>
+
+
// Code-behind
+Chart1.DataSource = GetMonthlyRevenue();
+Chart1.DataBind();
+
+
+
+
<Chart ID="Chart1" ChartWidth="600px" ChartHeight="400px"
+       Palette="ChartPalette.BrightPastel">
+    <ChartTitle Text="Sales Report" TitleDocking="Docking.Top" />
+    <ChartLegend Name="Legend1" LegendDocking="Docking.Bottom" />
+    <ChartSeries Name="Revenue" ChartType="SeriesChartType.Column"
+                 XValueMember="Month" YValueMembers="Amount"
+                 Items="@monthlyRevenue" />
+    <ChartArea Name="ChartArea1"
+               AxisX="@(new Axis { Title = "Month" })"
+               AxisY="@(new Axis { Title = "Amount ($)" })" />
+</Chart>
+
+@code {
+    private List<object> monthlyRevenue;
+
+    protected override void OnInitialized()
+    {
+        monthlyRevenue = GetMonthlyRevenue()
+            .Cast<object>().ToList();
+    }
+}
+
+
+
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/DataGrid/index.html b/site/DataControls/DataGrid/index.html new file mode 100644 index 000000000..2e97d1baa --- /dev/null +++ b/site/DataControls/DataGrid/index.html @@ -0,0 +1,5426 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DataGrid - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

DataGrid

+

The DataGrid component emulates the ASP.NET Web Forms asp:DataGrid control. It is defined in the System.Web.UI.WebControls.DataGrid class.

+

Features Supported in Blazor

+
    +
  • Readonly grid
    • +
  • Bound, Button, Hyperlink, and Template columns
    • +
  • Auto-generate columns
    • +
  • Show/Hide header row
    • +
  • Empty data text
    • +
  • Paging (AllowPaging, PageSize, CurrentPageIndex, PageIndexChanged event)
    • +
  • Sorting (AllowSorting, SortCommand event — sortable column headers)
    • +
  • Selection (SelectedIndex, SelectedIndexChanged event)
    • +
  • Editing (EditItemIndex — inline row editing support)
    • +
  • Style sub-components (ItemStyle, AlternatingItemStyle, HeaderStyle, FooterStyle, PagerStyle, SelectedItemStyle, EditItemStyle)
    • +
  • Caption property
    • +
  • GridLines property (None, Horizontal, Vertical, Both)
    • +
  • UseAccessibleHeader property (renders <th scope="col"> for accessibility)
    • +
  • CellPadding and CellSpacing properties
    • +
  • ShowFooter property
    • +
  • ItemCreated / ItemDataBound events
    • +
  • OnItemCommand, OnEditCommand, OnCancelCommand, OnUpdateCommand, OnDeleteCommand events
    • +
+

Blazor Notes

+
    +
  • The ItemCommand.CommandSource object will be populated with the ButtonField object
    • +
  • DataGrid uses the same column types as GridView (BoundField, ButtonField, etc.)
    • +
  • DataGrid is a legacy control superseded by GridView in ASP.NET 2.0, but is provided for compatibility
    • +
  • ItemType cascading - The ItemType parameter is automatically cascaded from the DataGrid to child columns. You only need to specify it once on the DataGrid, and all child columns (BoundField, TemplateField, HyperLinkField, ButtonField) will automatically infer the type. For backward compatibility, you can still explicitly specify ItemType on individual columns if desired.
    • +
+

Web Forms Features NOT Supported

+

The following DataGrid features from Web Forms are not currently supported:

+
    +
  • Custom paging (AllowCustomPaging, VirtualItemCount)
    • +
  • Footer templates
    • +
+

Syntax Comparison

+
+
+
+
<asp:DataGrid
+    AllowCustomPaging="True|False"
+    AllowPaging="True|False"
+    AllowSorting="True|False"
+    AutoGenerateColumns="True|False"
+    BackColor="color name|#dddddd"
+    BackImageUrl="uri"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|Inset|Outset"
+    BorderWidth="size"
+    CellPadding="integer"
+    CellSpacing="integer"
+    CssClass="string"
+    CurrentPageIndex="integer"
+    DataKeyField="string"
+    DataMember="string"
+    DataSource="string"
+    DataSourceID="string"
+    EditItemIndex="integer"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    GridLines="None|Horizontal|Vertical|Both"
+    HeaderStyle-BackColor="color name|#dddddd"
+    HeaderStyle-Font-Bold="True|False"
+    HorizontalAlign="NotSet|Left|Center|Right|Justify"
+    ID="string"
+    OnCancelCommand="CancelCommand event handler"
+    OnDataBinding="DataBinding event handler"
+    OnDeleteCommand="DeleteCommand event handler"
+    OnEditCommand="EditCommand event handler"
+    OnItemCommand="ItemCommand event handler"
+    OnItemCreated="ItemCreated event handler"
+    OnItemDataBound="ItemDataBound event handler"
+    OnPageIndexChanged="PageIndexChanged event handler"
+    OnSortCommand="SortCommand event handler"
+    OnUpdateCommand="UpdateCommand event handler"
+    PageSize="integer"
+    runat="server"
+    SelectedIndex="integer"
+    ShowFooter="True|False"
+    ShowHeader="True|False"
+    Visible="True|False"
+>
+    <AlternatingItemStyle />
+    <Columns>
+        <asp:BoundColumn
+            DataField="string"
+            DataFormatString="string"
+            FooterText="string"
+            HeaderImageUrl="uri"
+            HeaderText="string"
+            ReadOnly="True|False"
+            SortExpression="string"
+            Visible="True|False"
+        >
+            <FooterStyle />
+            <HeaderStyle />
+            <ItemStyle />
+        </asp:BoundColumn>
+        <asp:ButtonColumn
+            ButtonType="LinkButton|PushButton"
+            CausesValidation="True|False"
+            CommandName="string"
+            DataTextField="string"
+            DataTextFormatString="string"
+            FooterText="string"
+            HeaderImageUrl="uri"
+            HeaderText="string"
+            SortExpression="string"
+            Text="string"
+            ValidationGroup="string"
+            Visible="True|False"
+        />
+        <asp:HyperLinkColumn
+            DataNavigateUrlField="string"
+            DataNavigateUrlFormatString="string"
+            DataTextField="string"
+            DataTextFormatString="string"
+            FooterText="string"
+            HeaderImageUrl="uri"
+            HeaderText="string"
+            NavigateUrl="uri"
+            SortExpression="string"
+            Target="string"
+            Text="string"
+            Visible="True|False"
+        />
+        <asp:TemplateColumn
+            FooterText="string"
+            HeaderImageUrl="uri"
+            HeaderText="string"
+            SortExpression="string"
+            Visible="True|False"
+        >
+            <EditItemTemplate>
+                <!-- template content -->
+            </EditItemTemplate>
+            <FooterTemplate>
+                <!-- template content -->
+            </FooterTemplate>
+            <HeaderTemplate>
+                <!-- template content -->
+            </HeaderTemplate>
+            <ItemTemplate>
+                <!-- template content -->
+            </ItemTemplate>
+        </asp:TemplateColumn>
+    </Columns>
+    <EditItemStyle />
+    <FooterStyle />
+    <HeaderStyle />
+    <ItemStyle />
+    <PagerStyle Mode="NextPrev|NumericPages" />
+    <SelectedItemStyle />
+</asp:DataGrid>
+
+
+
+
<DataGrid
+    AllowPaging=bool
+    AllowSorting=bool
+    AutoGenerateColumns=bool
+    Caption=string
+    CellPadding=int
+    CellSpacing=int
+    CssClass=string
+    CurrentPageIndex=int
+    DataKeyField=string
+    DataSource=IEnumerable
+    EditItemIndex=int
+    EmptyDataText=string
+    Enabled=bool
+    GridLines=GridLines
+    ID=string
+    Items=IEnumerable
+    ItemType=Type
+    PageSize=int
+    SelectedIndex=int
+    OnDataBinding=EventCallBack
+    OnDataBound=EventCallBack
+    OnItemCommand=EventCallBack<DataGridCommandEventArgs>
+    OnEditCommand=EventCallBack<DataGridCommandEventArgs>
+    OnCancelCommand=EventCallBack<DataGridCommandEventArgs>
+    OnUpdateCommand=EventCallBack<DataGridCommandEventArgs>
+    OnDeleteCommand=EventCallBack<DataGridCommandEventArgs>
+    ItemCreated=EventCallback<DataGridItemEventArgs>
+    ItemDataBound=EventCallback<DataGridItemEventArgs>
+    PageIndexChanged=EventCallback<DataGridPageChangedEventArgs>
+    SortCommand=EventCallback<DataGridSortCommandEventArgs>
+    SelectedIndexChanged=EventCallback
+    OnInit=EventCallBack
+    OnLoad=EventCallBack
+    OnPreRender=EventCallBack
+    OnUnload=EventCallBack
+    OnDisposed=EventCallBack
+    SelectMethod=SelectHandler
+    ShowHeader=bool
+    ShowFooter=bool
+    TabIndex=int
+    UseAccessibleHeader=bool
+    Visible=bool
+>
+    <HeaderStyle BackColor=string ForeColor=string Font-Bold=bool ... />
+    <ItemStyle BackColor=string ForeColor=string ... />
+    <AlternatingItemStyle BackColor=string ForeColor=string ... />
+    <FooterStyle BackColor=string ForeColor=string Font-Italic=bool ... />
+    <PagerStyle BackColor=string ForeColor=string ... />
+    <SelectedItemStyle BackColor=string ForeColor=string ... />
+    <EditItemStyle BackColor=string ForeColor=string ... />
+    <Columns>
+        <BoundField
+            DataField=string
+            DataFormatString=string
+            HeaderText=string
+            Visible=bool
+        />
+        <HyperLinkField
+            DataNavigateUrlFields=string
+            DataNavigateUrlFormatString=string
+            DataTextField=string
+            DataTextFormatString=string
+            HeaderText=string
+            NavigateUrl=string
+            Target=string
+            Text=string
+            Visible=bool
+        />
+        <ButtonField
+            ButtonType=ButtonType
+            CommandName=string
+            DataTextField=string
+            DataTextFormatString=string
+            HeaderText=string
+            ImageUrl=string
+            Text=string
+            Visible=bool
+        />
+        <TemplateField
+            HeaderText=string
+            Visible=bool
+        >
+            <ItemTemplate>
+                <!-- template content -->
+            </ItemTemplate>
+        </TemplateField>
+    </Columns>
+</DataGrid>
+
+
+
+
+

Style Sub-Components

+

The DataGrid supports 7 style sub-components that control the appearance of different row types. Each is specified as a child element:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Style ComponentDescription
HeaderStyleStyles the header row
FooterStyleStyles the footer row
ItemStyleStyles normal data rows
AlternatingItemStyleStyles alternating data rows
PagerStyleStyles the pager row
SelectedItemStyleStyles the selected row
EditItemStyleStyles the row being edited
+

Each style component accepts standard style properties: BackColor, ForeColor, CssClass, Font-Bold, Font-Italic, Font-Size, HorizontalAlign, VerticalAlign, Width, Height, etc.

+

Caption Property

+

The Caption property renders a <caption> element inside the <table>, providing an accessible description of the table's purpose.

+

GridLines Property

+

Controls which table borders are displayed using the HTML rules attribute:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
GridLines.NoneNo grid lines
GridLines.HorizontalHorizontal lines only
GridLines.VerticalVertical lines only
GridLines.BothBoth horizontal and vertical lines
+

UseAccessibleHeader Property

+

When true, header cells render as <th scope="col"> instead of <td>, improving accessibility for screen readers.

+

Migration Example

+
+
+
+
<asp:DataGrid ID="dgCustomers" runat="server"
+    AutoGenerateColumns="False"
+    GridLines="Both"
+    Caption="Customer List">
+    <HeaderStyle BackColor="#4472C4" ForeColor="White" Font-Bold="True" />
+    <AlternatingItemStyle BackColor="#D6E4F0" />
+    <Columns>
+        <asp:BoundColumn DataField="CustomerID" HeaderText="ID" />
+        <asp:BoundColumn DataField="CompanyName" HeaderText="Company" />
+    </Columns>
+</asp:DataGrid>
+
+
+
+
<DataGrid ItemType="Customer"
+          AutoGenerateColumns="false"
+          GridLines="GridLines.Both"
+          Caption="Customer List"
+          UseAccessibleHeader="true"
+          SelectMethod="Customer.GetCustomers">
+    <HeaderStyle BackColor="#4472C4" ForeColor="#FFFFFF" Font-Bold="true" />
+    <AlternatingItemStyle BackColor="#D6E4F0" />
+    <Columns>
+        <BoundField DataField="CustomerID" HeaderText="ID" />
+        <BoundField DataField="CompanyName" HeaderText="Company" />
+    </Columns>
+</DataGrid>
+
+
+
+
+

Examples

+

Basic DataGrid with Manual Columns

+
<DataGrid ItemType="Customer"
+          AutoGenerateColumns="false"
+          DataKeyField="CustomerID"
+          SelectMethod="GetCustomers"
+          EmptyDataText="No data available">
+    <Columns>
+        <BoundField ItemType="Customer" DataField="CustomerID" HeaderText="ID" />
+        <BoundField ItemType="Customer" DataField="CompanyName" HeaderText="Company" />
+        <BoundField ItemType="Customer" DataField="FirstName" HeaderText="First Name"/>
+        <BoundField ItemType="Customer" DataField="LastName" HeaderText="Last Name"/>
+    </Columns>
+</DataGrid>
+
+

DataGrid with Auto-Generated Columns

+
<DataGrid ItemType="Customer"
+          DataKeyField="CustomerID"
+          SelectMethod="GetCustomers"
+          AutoGenerateColumns="true">
+</DataGrid>
+
+

DataGrid without Header

+
<DataGrid ItemType="Customer"
+          AutoGenerateColumns="false"
+          ShowHeader="false"
+          SelectMethod="GetCustomers">
+    <Columns>
+        <BoundField ItemType="Customer" DataField="CustomerID" HeaderText="ID" />
+        <BoundField ItemType="Customer" DataField="CompanyName" HeaderText="Company" />
+    </Columns>
+</DataGrid>
+
+

DataGrid with Paging

+
<DataGrid ItemType="Customer"
+          AutoGenerateColumns="true"
+          AllowPaging="true"
+          PageSize="5"
+          DataKeyField="CustomerID"
+          SelectMethod="GetCustomers"
+          PageIndexChanged="HandlePageChanged">
+    <PagerStyle BackColor="#DDDDDD" ForeColor="#333333" />
+</DataGrid>
+
+@code {
+    private void HandlePageChanged(DataGridPageChangedEventArgs e)
+    {
+        // e.NewPageIndex contains the new page index
+    }
+}
+
+

When AllowPaging="true" and PageSize is set, the DataGrid automatically renders a numeric pager row in the table footer. The pager displays page numbers — the current page as plain text, others as clickable links. Clicking a page number fires PageIndexChanged and navigates to that page.

+
+

DataGrid Paging vs. GridView/FormView/DetailsView Paging

+

DataGrid uses a built-in numeric pager and does not support the <PagerSettings> sub-component that GridView, FormView, and DetailsView use. If you need configurable pager modes (NextPrevious, NumericFirstLast, etc.), consider migrating to GridView which offers full PagerSettings support.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
AllowPagingboolfalseEnables or disables paging
PageSizeint10Number of items displayed per page
CurrentPageIndexint0The zero-based index of the current page
PageIndexChangedEventCallback<DataGridPageChangedEventArgs>—Fires when the page changes
+

The PagerStyle sub-component controls the visual appearance of the pager row.

+

DataGrid with Sorting

+
<DataGrid ItemType="Customer"
+          AutoGenerateColumns="false"
+          AllowSorting="true"
+          SelectMethod="GetCustomers"
+          SortCommand="HandleSort">
+    <Columns>
+        <BoundField DataField="CompanyName" HeaderText="Company" SortExpression="CompanyName" />
+        <BoundField DataField="ContactName" HeaderText="Contact" SortExpression="ContactName" />
+    </Columns>
+</DataGrid>
+
+@code {
+    private void HandleSort(DataGridSortCommandEventArgs e)
+    {
+        // e.SortExpression contains the column's SortExpression value
+        // Re-sort your data source and rebind
+    }
+}
+
+

Comparison with GridView

+

DataGrid and GridView are very similar in Blazor. The main differences are:

+
    +
  • DataGrid uses DataKeyField (singular) while GridView uses DataKeyNames
    • +
  • DataGrid event names use "Item" (OnItemCommand) while GridView uses "Row" (OnRowCommand)
    • +
  • DataGrid is a legacy control from ASP.NET 1.x, while GridView was introduced in ASP.NET 2.0
    • +
  • For new projects, GridView is recommended as it has more features and better design-time support
    • +
+

Both controls use the same column types (BoundField, ButtonField, HyperLinkField, TemplateField) and render similar HTML.

+

Migration from Web Forms

+

When migrating DataGrid from Web Forms to Blazor:

+
    +
  1. Replace <asp:DataGrid> with <DataGrid>
    2. +
  2. Replace runat="server" (not needed in Blazor)
    3. +
  3. Change DataKeyNames to DataKeyField if using
    4. +
  4. Update event handler names (e.g., OnItemCommand instead of event code-behind)
    5. +
  5. Use SelectMethod instead of setting DataSource in code-behind
    6. +
  6. Consider migrating to GridView for better feature support
    7. +
+

See Also

+
    +
  • GridView — The recommended data grid control for new projects
    • +
  • DataList — For custom layout of repeating data
    • +
  • Repeater — For lightweight data repetition
    • +
  • ListView — Full-featured list with CRUD and paging
    • +
  • DetailsView — Single record display
    • +
  • FormView — Custom single record layout
    • +
  • DataPager — Shared paging for multiple controls
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/DataList/index.html b/site/DataControls/DataList/index.html new file mode 100644 index 000000000..7c316e388 --- /dev/null +++ b/site/DataControls/DataList/index.html @@ -0,0 +1,4747 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DataList - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

DataList

+

The DataList component emulates the ASP.NET Web Forms asp:DataList control. It is defined in the System.Web.UI.WebControls.DataList class.

+

Features Supported in Blazor

+
    +
  • Flow Layout
      +
    • Empty List
      • +
    • FooterStyle
      • +
    • FooterTemplate
      • +
    • HeaderStyle
      • +
    • HeaderTemplate
      • +
    • Tooltip
      • +
    • Single Column
      • +
    +
    • +
  • Table Layout
      +
    • Accessible Headers
      • +
    • Empty List
      • +
    • FooterStyle
      • +
    • FooterTemplate
      • +
    • HeaderStyle
      • +
    • HeaderTemplate
      • +
    • Tooltip
      • +
    • Single Column
      • +
    • Tooltip
      • +
    +
    • +
+

Usage Notes

+
    +
  • The following Web Forms features are ignored
      +
    • runat="server"
      • +
    • EnableViewState
      • +
    +
    • +
  • ID should be converted to @ref if the component is referenced in code
    • +
  • ItemType MUST be defined as an attribute
    • +
  • 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
    • +
+

Syntax Comparison

+
+
+
+
<asp:DataList
+    AccessKey="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    Caption="string"
+    CaptionAlign="NotSet|Top|Bottom|Left|Right"
+    CellPadding="integer"
+    CellSpacing="integer"
+    CssClass="string"
+    DataKeyField="string"
+    DataMember="string"
+    DataSource="string"
+    DataSourceID="string"
+    EditItemIndex="integer"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ExtractTemplateRows="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    GridLines="None|Horizontal|Vertical|Both"
+    Height="size"
+    HorizontalAlign="NotSet|Left|Center|Right|Justify"
+    ID="string"
+    OnCancelCommand="CancelCommand event handler"
+    OnDataBinding="DataBinding event handler"
+    OnDeleteCommand="DeleteCommand event handler"
+    OnDisposed="Disposed event handler"
+    OnEditCommand="EditCommand event handler"
+    OnInit="Init event handler"
+    OnItemCommand="ItemCommand event handler"
+    OnItemCreated="ItemCreated event handler"
+    OnItemDataBound="ItemDataBound event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnSelectedIndexChanged="SelectedIndexChanged event handler"
+    OnUnload="Unload event handler"
+    OnUpdateCommand="UpdateCommand event handler"
+    RepeatColumns="integer"
+    RepeatDirection="Horizontal|Vertical"
+    RepeatLayout="Table|Flow"
+    runat="server"
+    SelectedIndex="integer"
+    ShowFooter="True|False"
+    ShowHeader="True|False"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    ToolTip="string"
+    UseAccessibleHeader="True|False"
+    Visible="True|False"
+    Width="size"
+>
+        <AlternatingItemStyle />
+        <AlternatingItemTemplate>
+            <!-- child controls -->
+        </AlternatingItemTemplate>
+        <EditItemStyle />
+        <EditItemTemplate>
+            <!-- child controls -->
+        </EditItemTemplate>
+        <FooterStyle />
+        <FooterTemplate>
+            <!-- child controls -->
+        </FooterTemplate>
+        <HeaderStyle />
+        <HeaderTemplate>
+            <!-- child controls -->
+        </HeaderTemplate>
+        <ItemStyle />
+        <ItemTemplate>
+            <!-- child controls -->
+        </ItemTemplate>
+        <SelectedItemStyle />
+        <SelectedItemTemplate>
+            <!-- child controls -->
+        </SelectedItemTemplate>
+        <SeparatorStyle />
+        <SeparatorTemplate>
+            <!-- child controls -->
+        </SeparatorTemplate>
+</asp:DataList>
+
+
+
+
<DataList ItemType="MyItem"
+    SelectMethod="GetItems"
+    RepeatLayout="RepeatLayout.Table"
+    RepeatDirection="RepeatDirection.Vertical"
+    RepeatColumns="1"
+    ShowHeader="true"
+    ShowFooter="true"
+    UseAccessibleHeader="true"
+    Visible="true">
+    <HeaderStyle BackColor="#CCCCCC" Font-Bold="true" />
+    <ItemStyle BackColor="#FFFFFF" />
+    <AlternatingItemStyle BackColor="#F5F5F5" />
+    <FooterStyle BackColor="#CCCCCC" />
+    <HeaderTemplate>
+        <strong>Items</strong>
+    </HeaderTemplate>
+    <ItemTemplate Context="Item">
+        @Item.Name
+    </ItemTemplate>
+    <FooterTemplate>
+        <em>End of list</em>
+    </FooterTemplate>
+</DataList>
+
+
+
+
+

See Also

+
    +
  • GridView — The recommended data grid control for new projects
    • +
  • DataGrid — Legacy grid control
    • +
  • Repeater — For lightweight data repetition
    • +
  • ListView — Full-featured list with CRUD and paging
    • +
  • DataPager — Shared paging for multiple controls
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/DataPager/index.html b/site/DataControls/DataPager/index.html new file mode 100644 index 000000000..5c7760565 --- /dev/null +++ b/site/DataControls/DataPager/index.html @@ -0,0 +1,4951 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DataPager - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

DataPager

+

The DataPager component provides paging functionality for data-bound controls. It displays navigation UI (page numbers, Previous/Next buttons, First/Last buttons) to navigate through large data sets.

+

Original Microsoft implementation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.datapager?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • TotalRowCount - Total number of items in the data source
    • +
  • PageSize - Number of items per page (default: 10)
    • +
  • PageIndex - Current page (zero-based)
    • +
  • PageButtonCount - Number of numeric page buttons to show (default: 5)
    • +
  • Mode - PagerButtons enum (Numeric, NextPrevious, NextPreviousFirstLast, NumericFirstLast)
    • +
  • Custom button text - FirstPageText, PreviousPageText, NextPageText, LastPageText
    • +
  • Events - OnPageIndexChanging (cancellable), OnPageIndexChanged
    • +
  • StartRowIndex / MaximumRows - Properties for data slicing
    • +
+

Blazor Notes

+

Unlike Web Forms, which links DataPager to ListView via PagedControlID, the Blazor implementation uses two-way binding. You manage the page index in your component and pass it to both the DataPager and your data query.

+

The DataPager provides StartRowIndex and MaximumRows properties that you can use to slice your data:

+
var pagedData = allData.Skip(dataPager.StartRowIndex).Take(dataPager.MaximumRows);
+
+

Web Forms Features NOT Supported

+
    +
  • PagedControlID - Not supported; use two-way binding instead
    • +
  • Fields collection - Not supported; use Mode property for common layouts
    • +
  • QueryStringField - Not supported; implement URL-based paging separately
    • +
+

Syntax Comparison

+
+
+
+
<asp:DataPager
+    ID="DataPager1"
+    PagedControlID="ListView1"
+    PageSize="10"
+    QueryStringField="page"
+    runat="server">
+    <Fields>
+        <asp:NextPreviousPagerField
+            ButtonType="Link"
+            FirstPageText="First"
+            LastPageText="Last"
+            NextPageText="Next"
+            PreviousPageText="Previous"
+            ShowFirstPageButton="true"
+            ShowLastPageButton="true"
+            ShowNextPageButton="true"
+            ShowPreviousPageButton="true" />
+        <asp:NumericPagerField
+            ButtonCount="5"
+            ButtonType="Link" />
+    </Fields>
+</asp:DataPager>
+
+
+
+
<DataPager
+    TotalRowCount="@TotalItems"
+    PageSize="10"
+    @bind-PageIndex="CurrentPage"
+    Mode="PagerButtons.NumericFirstLast"
+    FirstPageText="First"
+    LastPageText="Last"
+    PageButtonCount="5" />
+
+
+
+
+

Usage Notes

+
    +
  1. Manage state externally - The DataPager doesn't fetch data; you handle paging logic
    2. +
  2. Use @bind-PageIndex - For two-way binding of the current page
    3. +
  3. Subscribe to events - Use OnPageIndexChanging to cancel navigation or OnPageIndexChanged for side effects
    4. +
  4. Slice your data - Use Skip() and Take() based on StartRowIndex and MaximumRows
    5. +
+

Examples

+

Basic Usage with ListView

+
@* Data paging with ListView *@
+<ListView TItem="Product" DataSource="@PagedProducts">
+    <ItemTemplate Context="product">
+        <div>@product.Name - @product.Price.ToString("C")</div>
+    </ItemTemplate>
+</ListView>
+
+<DataPager 
+    TotalRowCount="@AllProducts.Count" 
+    PageSize="10" 
+    @bind-PageIndex="CurrentPage" />
+
+@code {
+    private List<Product> AllProducts = GetAllProducts();
+    private int CurrentPage = 0;
+
+    private IEnumerable<Product> PagedProducts => 
+        AllProducts.Skip(CurrentPage * 10).Take(10);
+}
+
+

Next/Previous Navigation

+
@* Simple Previous/Next buttons *@
+<DataPager 
+    TotalRowCount="100" 
+    PageSize="10" 
+    @bind-PageIndex="PageIndex"
+    Mode="PagerButtons.NextPrevious" />
+
+

Full Navigation with Numbers

+
@* All navigation options *@
+<DataPager 
+    TotalRowCount="@Data.Count" 
+    PageSize="20" 
+    @bind-PageIndex="PageIndex"
+    Mode="PagerButtons.NumericFirstLast"
+    PageButtonCount="7"
+    FirstPageText="<<"
+    PreviousPageText="<"
+    NextPageText=">"
+    LastPageText=">>" />
+
+

Handling Page Changes

+
<DataPager 
+    TotalRowCount="@TotalCount" 
+    PageSize="10" 
+    @bind-PageIndex="PageIndex"
+    OnPageIndexChanging="HandlePageChanging"
+    OnPageIndexChanged="HandlePageChanged" />
+
+@code {
+    private async Task HandlePageChanging(PageChangedEventArgs args)
+    {
+        // Cancel if there are unsaved changes
+        if (HasUnsavedChanges)
+        {
+            args.Cancel = true;
+            ShowWarning("Please save your changes first.");
+        }
+    }
+
+    private async Task HandlePageChanged(PageChangedEventArgs args)
+    {
+        // Log or track page navigation
+        await LogPageView(args.NewPageIndex);
+    }
+}
+
+

Custom Styling

+
<DataPager 
+    TotalRowCount="100" 
+    PageSize="10" 
+    @bind-PageIndex="PageIndex"
+    CssClass="pagination"
+    Mode="PagerButtons.Numeric" />
+
+<style>
+    .pagination a { 
+        padding: 5px 10px; 
+        margin: 0 2px; 
+        border: 1px solid #ccc; 
+    }
+    .pagination .aspNetCurrentPage { 
+        font-weight: bold; 
+        background: #007bff; 
+        color: white; 
+        padding: 5px 10px; 
+    }
+    .pagination .aspNetDisabled { 
+        color: #ccc; 
+        pointer-events: none; 
+    }
+</style>
+
+

See Also

+
    +
  • ListView — Full-featured list with built-in paging
    • +
  • GridView — Multi-record tabular display
    • +
  • Repeater — For lightweight data repetition
    • +
  • DataList — For repeating data with layout options
    • +
  • DetailsView — Single record display
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/DetailsView/index.html b/site/DataControls/DetailsView/index.html new file mode 100644 index 000000000..22bd90eba --- /dev/null +++ b/site/DataControls/DetailsView/index.html @@ -0,0 +1,5212 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DetailsView - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

DetailsView

+

The DetailsView component emulates the ASP.NET Web Forms asp:DetailsView control. It displays a single record from a data source in a vertical table layout, with one row per field. It supports read-only, edit, and insert modes, paging between records, and auto-generated or explicitly defined fields.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.detailsview?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Single-record display in a two-column table (label + value per row)
    • +
  • AutoGenerateRows — automatically generates rows from the data item's public properties
    • +
  • Three display modes via DetailsViewMode enum: ReadOnly, Edit, Insert
    • +
  • DefaultMode — sets the initial mode
    • +
  • ModeChanging / ModeChanged events
    • +
  • AutoGenerateEditButton, AutoGenerateDeleteButton, AutoGenerateInsertButton — command row buttons
    • +
  • CRUD events: ItemCommand, ItemDeleting / ItemDeleted, ItemInserting / ItemInserted, ItemUpdating / ItemUpdated
    • +
  • Cancellable pre-operation events (ItemDeleting, ItemInserting, ItemUpdating)
    • +
  • AllowPaging with numeric pager — navigate between items in the data source
    • +
  • PageIndex / PageIndexChanging / PageIndexChanged events
    • +
  • DataKeyNames — primary key field identification
    • +
  • HeaderText / HeaderTemplate, FooterText / FooterTemplate
    • +
  • EmptyDataText / EmptyDataTemplate — displayed when data source is empty
    • +
  • PagerTemplate — custom pager UI
    • +
  • Fields — explicit field definitions (BoundField, TemplateField)
    • +
  • GridLines, CellPadding, CellSpacing — table layout control
    • +
  • CssClass — CSS class on the outer table
    • +
  • Caption / CaptionAlign — renders a <caption> element for table accessibility
    • +
  • Visible — show/hide the entire control
    • +
  • Generic ItemType for strongly typed data binding
    • +
  • Style sub-components (RowStyle, AlternatingRowStyle, HeaderStyle, FooterStyle, CommandRowStyle, EditRowStyle, InsertRowStyle, FieldHeaderStyle, EmptyDataRowStyle, PagerStyle)
    • +
  • PagerSettings — configurable pager button modes, text, images, and position
    • +
+

Blazor Notes

+
    +
  • The component is generic: DetailsView<ItemType>. You must specify ItemType when using it.
    • +
  • Field definitions are added as child content inside a <Fields> block. They register themselves with the parent via a CascadingValue.
    • +
  • When AutoGenerateRows="true" (the default) and no explicit fields are defined, the component reflects over ItemType to generate rows for each public readable property.
    • +
  • The pager displays one page number per item in the data source (each "page" is one record).
    • +
+

Web Forms Features NOT Supported

+
    +
  • DataSourceID — Blazor does not use server-side data source controls; bind data directly via Items
    • +
  • Sorting — AllowSorting is not implemented
    • +
  • CommandField / ButtonField columns — Use AutoGenerateEditButton / AutoGenerateDeleteButton / AutoGenerateInsertButton or custom templates
    • +
  • ViewState — Not needed; Blazor preserves component state natively
    • +
  • Theming / SkinID — Not applicable to Blazor
    • +
+

Syntax Comparison

+
+
+
+
<asp:DetailsView
+    AllowPaging="True|False"
+    AutoGenerateDeleteButton="True|False"
+    AutoGenerateEditButton="True|False"
+    AutoGenerateInsertButton="True|False"
+    AutoGenerateRows="True|False"
+    Caption="string"
+    CaptionAlign="NotSet|Top|Bottom|Left|Right"
+    CellPadding="integer"
+    CellSpacing="integer"
+    CssClass="string"
+    DataKeyNames="string"
+    DataSourceID="string"
+    DefaultMode="ReadOnly|Edit|Insert"
+    EmptyDataText="string"
+    GridLines="None|Horizontal|Vertical|Both"
+    HeaderText="string"
+    FooterText="string"
+    ID="string"
+    OnItemCommand="ItemCommand event handler"
+    OnItemDeleted="ItemDeleted event handler"
+    OnItemDeleting="ItemDeleting event handler"
+    OnItemInserted="ItemInserted event handler"
+    OnItemInserting="ItemInserting event handler"
+    OnItemUpdated="ItemUpdated event handler"
+    OnItemUpdating="ItemUpdating event handler"
+    OnModeChanged="ModeChanged event handler"
+    OnModeChanging="ModeChanging event handler"
+    OnPageIndexChanged="PageIndexChanged event handler"
+    OnPageIndexChanging="PageIndexChanging event handler"
+    PageIndex="integer"
+    Visible="True|False"
+    runat="server"
+>
+    <AlternatingRowStyle />
+    <CommandRowStyle />
+    <EditRowStyle />
+    <EmptyDataRowStyle />
+    <FieldHeaderStyle />
+    <FooterStyle />
+    <HeaderStyle />
+    <InsertRowStyle />
+    <PagerSettings
+        Mode="NextPrevious|Numeric|NextPreviousFirstLast|NumericFirstLast"
+        FirstPageText="string"
+        LastPageText="string"
+        NextPageText="string"
+        PreviousPageText="string"
+        PageButtonCount="integer"
+        Position="Bottom|Top|TopAndBottom"
+        Visible="True|False"
+    />
+    <PagerStyle />
+    <RowStyle />
+    <Fields>
+        <asp:BoundField DataField="string" HeaderText="string" ReadOnly="True|False" />
+        <asp:TemplateField HeaderText="string">
+            <ItemTemplate><!-- child controls --></ItemTemplate>
+            <EditItemTemplate><!-- child controls --></EditItemTemplate>
+        </asp:TemplateField>
+    </Fields>
+    <HeaderTemplate><!-- child controls --></HeaderTemplate>
+    <FooterTemplate><!-- child controls --></FooterTemplate>
+    <EmptyDataTemplate><!-- child controls --></EmptyDataTemplate>
+    <PagerTemplate><!-- child controls --></PagerTemplate>
+</asp:DetailsView>
+
+
+
+
<DetailsView ItemType="Product"
+    Items="@Products"
+    AutoGenerateRows="true"
+    AllowPaging="true"
+    AutoGenerateEditButton="true"
+    AutoGenerateDeleteButton="true"
+    DefaultMode="DetailsViewMode.ReadOnly"
+    HeaderText="Product Details"
+    EmptyDataText="No products found."
+    Caption="Product Record"
+    CaptionAlign="TableCaptionAlign.Top"
+    CssClass="details-grid"
+    GridLines="GridLines.Both"
+    ItemDeleting="HandleDeleting"
+    ItemUpdating="HandleUpdating"
+    ModeChanging="HandleModeChanging"
+    PageIndexChanging="HandlePageChanging">
+    <PagerSettings Mode="PagerButtons.NumericFirstLast"
+                   FirstPageText="First"
+                   LastPageText="Last"
+                   Position="PagerPosition.Bottom" />
+    <RowStyle BackColor="#FFFFFF" />
+    <AlternatingRowStyle BackColor="#F7F7F7" />
+    <HeaderStyle BackColor="#336699" ForeColor="#FFFFFF" Font-Bold="true" />
+    <FooterStyle BackColor="#CCCCCC" />
+    <CommandRowStyle BackColor="#EEEEEE" />
+    <FieldHeaderStyle Font-Bold="true" />
+    <PagerStyle BackColor="#DDDDDD" HorizontalAlign="HorizontalAlign.Center" />
+</DetailsView>
+
+@code {
+    private List<Product> Products = new();
+
+    private void HandleDeleting(DetailsViewDeleteEventArgs e)
+    {
+        // e.RowIndex gives you the current page index
+        // Perform delete logic; set e.Cancel = true to abort
+    }
+
+    private void HandleUpdating(DetailsViewUpdateEventArgs e)
+    {
+        // Perform update logic; set e.Cancel = true to abort
+    }
+
+    private void HandleModeChanging(DetailsViewModeEventArgs e)
+    {
+        // e.NewMode tells you the target mode
+        // e.CancelingEdit tells you if this is a cancel operation
+    }
+
+    private void HandlePageChanging(PageChangedEventArgs e)
+    {
+        // e.NewPageIndex gives you the target page
+    }
+}
+
+
+
+
+

With Explicit Fields

+
<DetailsView ItemType="Product"
+    Items="@Products"
+    AutoGenerateRows="false"
+    AllowPaging="true">
+    <Fields>
+        <BoundField DataField="Name" HeaderText="Product Name" />
+        <BoundField DataField="Price" HeaderText="Unit Price" />
+        <TemplateField HeaderText="Actions">
+            <ItemTemplate>
+                <a href="/products/@context.Id">View</a>
+            </ItemTemplate>
+        </TemplateField>
+    </Fields>
+</DetailsView>
+
+

With Custom Templates

+
<DetailsView ItemType="Product"
+    Items="@Products"
+    AutoGenerateRows="true">
+    <HeaderTemplate>
+        <strong>Product Information</strong>
+    </HeaderTemplate>
+    <EmptyDataTemplate>
+        <p>No products available. <a href="/products/new">Add one</a>.</p>
+    </EmptyDataTemplate>
+    <FooterTemplate>
+        <em>Last updated: @DateTime.Now.ToShortDateString()</em>
+    </FooterTemplate>
+</DetailsView>
+
+

HTML Output

+

The component renders a table with one row per field, matching the Web Forms DetailsView output:

+
<table cellspacing="0" rules="all" border="1"
+       style="border-collapse:collapse" class="details-grid">
+  <!-- Header Row -->
+  <tr>
+    <td colspan="2">Product Details</td>
+  </tr>
+  <!-- Field Rows (one per property or defined field) -->
+  <tr>
+    <td>Id</td>
+    <td>1</td>
+  </tr>
+  <tr>
+    <td>Name</td>
+    <td>Widget</td>
+  </tr>
+  <tr>
+    <td>Price</td>
+    <td>9.99</td>
+  </tr>
+  <!-- Command Row (when edit/delete/insert buttons enabled) -->
+  <tr>
+    <td colspan="2">
+      <a href="javascript:void(0);">Edit</a>&nbsp;
+      <a href="javascript:void(0);">Delete</a>
+    </td>
+  </tr>
+  <!-- Pager Row (when AllowPaging and multiple items) -->
+  <tr>
+    <td colspan="2">
+      <table>
+        <tr>
+          <td><span>1</span></td>
+          <td><a href="javascript:void(0);">2</a></td>
+          <td><a href="javascript:void(0);">3</a></td>
+        </tr>
+      </table>
+    </td>
+  </tr>
+  <!-- Footer Row -->
+  <tr>
+    <td colspan="2">Footer text here</td>
+  </tr>
+</table>
+
+

In Edit or Insert mode, the command row changes to show Update/Cancel or Insert/Cancel links:

+
<!-- Edit mode command row -->
+<tr>
+  <td colspan="2">
+    <a href="javascript:void(0);">Update</a>&nbsp;
+    <a href="javascript:void(0);">Cancel</a>
+  </td>
+</tr>
+
+

Style Sub-Components

+

The DetailsView supports style sub-components that control the appearance of different row types. Each is specified as a child element:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Style ComponentDescription
RowStyleStyles normal data rows
AlternatingRowStyleStyles alternating data rows
HeaderStyleStyles the header row
FooterStyleStyles the footer row
CommandRowStyleStyles the command row (Edit/Delete/Insert buttons)
EditRowStyleStyles rows in Edit mode
InsertRowStyleStyles rows in Insert mode
FieldHeaderStyleStyles the field label cells (left column)
EmptyDataRowStyleStyles the empty data row
PagerStyleStyles the pager row
+

Each style component accepts standard style properties: BackColor, ForeColor, CssClass, Font-Bold, Font-Italic, Font-Size, HorizontalAlign, VerticalAlign, Width, Height, etc.

+

Caption Property

+

The Caption and CaptionAlign properties render a <caption> element inside the <table>, providing an accessible description of the table's purpose:

+
<DetailsView ItemType="Product" Items="@Products"
+    Caption="Product Details"
+    CaptionAlign="TableCaptionAlign.Top" />
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CaptionAlign ValueEffect
NotSetDefault browser positioning
TopCaption above the table
BottomCaption below the table
LeftCaption text left-aligned
RightCaption text right-aligned
+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:DetailsView> to <DetailsView>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Add ItemType — The Blazor component is generic; specify ItemType="YourClass"
    4. +
  4. Replace DataSourceID — Use Items="@yourCollection" instead of binding to a server-side DataSource control
    5. +
  5. Field declarations — Remove asp: prefix from <asp:BoundField> and <asp:TemplateField>; place them inside <Fields> block
    6. +
  6. Event signatures — Events use typed EventArgs classes (DetailsViewDeleteEventArgs, DetailsViewUpdateEventArgs, etc.)
    7. +
  7. Styles — Web Forms <HeaderStyle>, <RowStyle>, etc. work as child elements in Blazor with the same property names (BackColor, ForeColor, Font-Bold, etc.)
    8. +
  8. PagerSettings — Configure via child <PagerSettings> element instead of dash-separated attributes. See PagerSettings for details.
    9. +
+

Migration Example

+
+
+
+
<asp:DetailsView ID="dvProduct"
+    DataSourceID="SqlDataSource1"
+    AutoGenerateRows="True"
+    AllowPaging="True"
+    AutoGenerateEditButton="True"
+    OnItemUpdating="dvProduct_ItemUpdating"
+    runat="server">
+    <HeaderStyle BackColor="#336699" ForeColor="White" />
+</asp:DetailsView>
+
+
+
+
<DetailsView ItemType="Product"
+    Items="@Products"
+    AutoGenerateRows="true"
+    AllowPaging="true"
+    AutoGenerateEditButton="true"
+    CssClass="product-details"
+    ItemUpdating="HandleUpdating">
+    <HeaderStyle BackColor="#336699" ForeColor="#FFFFFF" />
+</DetailsView>
+
+@code {
+    private List<Product> Products = new();
+
+    protected override async Task OnInitializedAsync()
+    {
+        Products = await ProductService.GetAllAsync();
+    }
+
+    private void HandleUpdating(DetailsViewUpdateEventArgs e)
+    {
+        // Perform update
+    }
+}
+
+
+
+
+

See Also

+
    +
  • FormView — Similar single-record view with full template control
    • +
  • GridView — Multi-record tabular display with similar field types
    • +
  • DataList — Repeating data display
    • +
  • ListView — Full-featured list with CRUD and paging
    • +
  • DataPager — Shared paging for multiple controls
    • +
  • PagerSettings — Shared pager configuration
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/FormView/index.html b/site/DataControls/FormView/index.html new file mode 100644 index 000000000..adbbfaa0b --- /dev/null +++ b/site/DataControls/FormView/index.html @@ -0,0 +1,5251 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FormView - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

FormView

+ +

The FormView component is meant to emulate the asp:FormView control in markup and is defined in the System.Web.UI.WebControls.FormView class

+

Features supported in Blazor

+
    +
  • Readonly Form
    • +
  • Numerical Pager
    • +
  • OnDataBinding and OnDataBound events trigger
    • +
  • ModeChanging and ModeChanged events
    • +
  • Insert, Edit, Update, Delete actions and supporting events:
      +
    • OnItemDeleting / OnItemDeleted — before and after delete operations
      • +
    • OnItemInserting / OnItemInserted — before and after insert operations
      • +
    • OnItemUpdating / OnItemUpdated — before and after update operations
      • +
    +
    • +
  • ItemCommand event — fires when any command button within the FormView is clicked
    • +
  • ItemCreated event — fires when the FormView is first created and data-bound
    • +
  • PageIndexChanging / PageIndexChanged events — fires when paging occurs (cancellable)
    • +
  • HeaderText / HeaderTemplate - Renders a header row above the form content. HeaderTemplate takes precedence over HeaderText when both are specified.
    • +
  • FooterText / FooterTemplate - Renders a footer row below the form content. FooterTemplate takes precedence over FooterText when both are specified.
    • +
  • EmptyDataText / EmptyDataTemplate - Displays content when the data source is empty or null. EmptyDataTemplate takes precedence over EmptyDataText when both are specified.
    • +
  • PagerTemplate — custom pager UI replacing the default numeric pager
    • +
  • Caption / CaptionAlign — renders a <caption> element for table accessibility
    • +
  • Style sub-components (RowStyle, EditRowStyle, InsertRowStyle, HeaderStyle, FooterStyle, EmptyDataRowStyle, PagerStyle)
    • +
  • PagerSettings — configurable pager button modes, text, images, and position
    • +
+

Web Forms Features NOT Supported

+
    +
  • DataSourceID — Blazor does not use server-side data source controls; bind data directly via DataSource
    • +
  • ViewState / EnableViewState — Not needed; Blazor preserves component state natively
    • +
  • Theming / SkinID / EnableTheming — Not applicable to Blazor
    • +
  • RenderTable — Not implemented; the FormView always renders a table
    • +
+

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
    • +
  • Template precedence - When both a text property and its corresponding template are set, the template always takes precedence (e.g., HeaderTemplate overrides HeaderText)
    • +
+

Syntax Comparison

+
+
+
+
<asp:FormView
+    AccessKey="string"
+    AllowPaging="True|False"
+    BackColor="color name|#dddddd"
+    BackImageUrl="uri"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    Caption="string"
+    CaptionAlign="NotSet|Top|Bottom|Left|Right"
+    CellPadding="integer"
+    CellSpacing="integer"
+    CssClass="string"
+    DataKeyNames="string"
+    DataMember="string"
+    DataSource="string"
+    DataSourceID="string"
+    DefaultMode="ReadOnly|Edit|Insert"
+    EmptyDataText="string"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    FooterText="string"
+    ForeColor="color name|#dddddd"
+    GridLines="None|Horizontal|Vertical|Both"
+    HeaderText="string"
+    Height="size"
+    HorizontalAlign="NotSet|Left|Center|Right|Justify"
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnDataBound="DataBound event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnItemCommand="ItemCommand event handler"
+    OnItemCreated="ItemCreated event handler"
+    OnItemDeleted="ItemDeleted event handler"
+    OnItemDeleting="ItemDeleting event handler"
+    OnItemInserted="ItemInserted event handler"
+    OnItemInserting="ItemInserting event handler"
+    OnItemUpdated="ItemUpdated event handler"
+    OnItemUpdating="ItemUpdating event handler"
+    OnLoad="Load event handler"
+    OnModeChanged="ModeChanged event handler"
+    OnModeChanging="ModeChanging event handler"
+    OnPageIndexChanged="PageIndexChanged event handler"
+    OnPageIndexChanging="PageIndexChanging event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    PageIndex="integer"
+    PagerSettings-FirstPageImageUrl="uri"
+    PagerSettings-FirstPageText="string"
+    PagerSettings-LastPageImageUrl="uri"
+    PagerSettings-LastPageText="string"
+    PagerSettings-Mode="NextPrevious|Numeric|NextPreviousFirstLast|
+        NumericFirstLast"
+    PagerSettings-NextPageImageUrl="uri"
+    PagerSettings-NextPageText="string"
+    PagerSettings-PageButtonCount="integer"
+    PagerSettings-Position="Bottom|Top|TopAndBottom"
+    PagerSettings-PreviousPageImageUrl="uri"
+    PagerSettings-PreviousPageText="string"
+    PagerSettings-Visible="True|False"
+    RenderTable="True|False"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+>
+        <EditItemTemplate>
+            <!-- child controls -->
+        </EditItemTemplate>
+        <EditRowStyle />
+        <EmptyDataRowStyle />
+        <EmptyDataTemplate>
+            <!-- child controls -->
+        </EmptyDataTemplate>
+        <FooterStyle />
+        <FooterTemplate>
+            <!-- child controls -->
+        </FooterTemplate>
+        <HeaderStyle />
+        <HeaderTemplate>
+            <!-- child controls -->
+        </HeaderTemplate>
+        <InsertItemTemplate>
+            <!-- child controls -->
+        </InsertItemTemplate>
+        <InsertRowStyle />
+        <ItemTemplate>
+            <!-- child controls -->
+        </ItemTemplate>
+        <PagerSettings
+            FirstPageImageUrl="uri"
+            FirstPageText="string"
+            LastPageImageUrl="uri"
+            LastPageText="string"
+            Mode="NextPrevious|Numeric|NextPreviousFirstLast|
+                NumericFirstLast"
+            NextPageImageUrl="uri"
+            NextPageText="string"
+            OnPropertyChanged="PropertyChanged event handler"
+            PageButtonCount="integer"
+            Position="Bottom|Top|TopAndBottom"
+            PreviousPageImageUrl="uri"
+            PreviousPageText="string"
+            Visible="True|False"
+        />
+        <PagerStyle />
+        <PagerTemplate>
+            <!-- child controls -->
+        </PagerTemplate>
+        <RowStyle />
+</asp:FormView>
+
+
+
+
<FormView
+    DataSource=IEnumerable
+    DefaultMode="ReadOnly|Edit|Insert"
+    Caption=string
+    CaptionAlign="NotSet|Top|Bottom|Left|Right"
+    EmptyDataText=string
+    HeaderText=string
+    FooterText=string
+    ItemType=Type
+    ItemCommand=EventCallback<FormViewCommandEventArgs>
+    ItemCreated=EventCallback
+    ModeChanging=EventCallback<FormViewModeEventArgs>
+    ModeChanged=EventCallback<FormViewModeEventArgs>
+    OnDataBinding=EventCallBack
+    OnDataBound=EventCallBack
+    OnItemDeleting=EventCallBack<FormViewDeleteEventArgs>
+    OnItemDeleted=EventCallBack<FormViewDeletedEventArgs>
+    OnItemInserting=EventCallBack<FormViewInsertEventArgs>
+    OnItemInserted=EventCallBack<FormViewInsertEventArgs>
+    OnItemUpdating=EventCallBack<FormViewUpdateEventArgs>
+    OnItemUpdated=EventCallBack<FormViewUpdatedEventArgs>
+    PageIndexChanging=EventCallback<PageChangedEventArgs>
+    PageIndexChanged=EventCallback<PageChangedEventArgs>
+    SelectMethod=SelectHandler
+    Visible=bool
+>
+    <PagerSettings Mode="PagerButtons.Numeric"
+                   NextPageText="string"
+                   PreviousPageText="string"
+                   Position="PagerPosition.Bottom" />
+    <RowStyle BackColor=string ForeColor=string CssClass=string ... />
+    <EditRowStyle BackColor=string ForeColor=string ... />
+    <InsertRowStyle BackColor=string ForeColor=string ... />
+    <HeaderStyle BackColor=string ForeColor=string ... />
+    <FooterStyle BackColor=string ForeColor=string ... />
+    <EmptyDataRowStyle BackColor=string ForeColor=string ... />
+    <PagerStyle BackColor=string ForeColor=string ... />
+    <HeaderTemplate>
+        <!-- custom header content -->
+    </HeaderTemplate>
+    <ItemTemplate Context="Item">
+        <!-- read-only display -->
+    </ItemTemplate>
+    <EditItemTemplate Context="Item">
+        <!-- edit form -->
+    </EditItemTemplate>
+    <InsertItemTemplate Context="Item">
+        <!-- insert form -->
+    </InsertItemTemplate>
+    <EmptyDataTemplate>
+        <!-- content shown when data source is empty -->
+    </EmptyDataTemplate>
+    <PagerTemplate>
+        <!-- custom pager content -->
+    </PagerTemplate>
+    <FooterTemplate>
+        <!-- custom footer content -->
+    </FooterTemplate>
+</FormView>
+
+
+
+
+

Style Sub-Components

+

The FormView supports style sub-components that control the appearance of different sections. Each is specified as a child element:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Style ComponentDescription
RowStyleStyles the data row in ReadOnly mode
EditRowStyleStyles the data row in Edit mode
InsertRowStyleStyles the data row in Insert mode
HeaderStyleStyles the header row
FooterStyleStyles the footer row
EmptyDataRowStyleStyles the empty data row
PagerStyleStyles the pager row
+

Each style component accepts standard style properties: BackColor, ForeColor, CssClass, Font-Bold, Font-Italic, Font-Size, HorizontalAlign, VerticalAlign, Width, Height, etc.

+

Examples

+ +
<FormView DataSource="@Employees"
+          ItemType="Employee"
+          HeaderText="Employee Details"
+          FooterText="End of record"
+          EmptyDataText="No employees found.">
+    <ItemTemplate Context="Item">
+        <p><strong>Name:</strong> @Item.Name</p>
+        <p><strong>Title:</strong> @Item.Title</p>
+    </ItemTemplate>
+</FormView>
+
+@code {
+    private List<Employee> Employees = new()
+    {
+        new Employee { Name = "Jane Smith", Title = "Developer" }
+    };
+
+    public class Employee
+    {
+        public string Name { get; set; } = "";
+        public string Title { get; set; } = "";
+    }
+}
+
+ +
<FormView DataSource="@Products" ItemType="Product">
+    <HeaderTemplate>
+        <div class="form-header">
+            <h3>Product Information</h3>
+            <hr />
+        </div>
+    </HeaderTemplate>
+    <ItemTemplate Context="Item">
+        <p><strong>Product:</strong> @Item.Name</p>
+        <p><strong>Price:</strong> @Item.Price.ToString("C")</p>
+    </ItemTemplate>
+    <FooterTemplate>
+        <div class="form-footer">
+            <hr />
+            <small>Last updated: @DateTime.Now.ToShortDateString()</small>
+        </div>
+    </FooterTemplate>
+</FormView>
+
+@code {
+    private List<Product> Products = new()
+    {
+        new Product { Name = "Widget", Price = 9.99m }
+    };
+
+    public class Product
+    {
+        public string Name { get; set; } = "";
+        public decimal Price { get; set; }
+    }
+}
+
+

Empty Data Template

+
@* Shows custom content when no data is available *@
+<FormView DataSource="@FilteredItems" ItemType="Order">
+    <ItemTemplate Context="Item">
+        <p>Order #@Item.Id — @Item.Description</p>
+    </ItemTemplate>
+    <EmptyDataTemplate>
+        <div class="alert alert-info">
+            <strong>No orders found.</strong> Try adjusting your search criteria.
+        </div>
+    </EmptyDataTemplate>
+</FormView>
+
+@code {
+    private List<Order> FilteredItems = new(); // empty list
+
+    public class Order
+    {
+        public int Id { get; set; }
+        public string Description { get; set; } = "";
+    }
+}
+
+ +
+
+
+
<asp:FormView ID="FormView1" runat="server"
+              HeaderText="Customer Record"
+              FooterText="End of record"
+              EmptyDataText="No customer data available.">
+    <ItemTemplate>
+        <p><%# Eval("Name") %></p>
+    </ItemTemplate>
+</asp:FormView>
+
+
+
+
<FormView DataSource="@Customers"
+          ItemType="Customer"
+          HeaderText="Customer Record"
+          FooterText="End of record"
+          EmptyDataText="No customer data available.">
+    <ItemTemplate Context="Item">
+        <p>@Item.Name</p>
+    </ItemTemplate>
+</FormView>
+
+
+
+
+

Migration Example: With Templates

+
+
+
+
<asp:FormView ID="FormView1" runat="server">
+    <HeaderTemplate>
+        <h3>Customer Record</h3>
+    </HeaderTemplate>
+    <ItemTemplate>
+        <p><%# Eval("Name") %></p>
+    </ItemTemplate>
+    <EmptyDataTemplate>
+        <p>No data found.</p>
+    </EmptyDataTemplate>
+    <FooterTemplate>
+        <small>End of record</small>
+    </FooterTemplate>
+</asp:FormView>
+
+
+
+
<FormView DataSource="@Customers" ItemType="Customer">
+    <HeaderTemplate>
+        <h3>Customer Record</h3>
+    </HeaderTemplate>
+    <ItemTemplate Context="Item">
+        <p>@Item.Name</p>
+    </ItemTemplate>
+    <EmptyDataTemplate>
+        <p>No data found.</p>
+    </EmptyDataTemplate>
+    <FooterTemplate>
+        <small>End of record</small>
+    </FooterTemplate>
+</FormView>
+
+
+
+
+

CRUD Event Handling

+
<FormView DataSource="@Customers" ItemType="Customer" DefaultMode="FormViewMode.ReadOnly"
+          OnItemUpdating="HandleUpdating"
+          OnItemUpdated="HandleUpdated"
+          OnItemDeleting="HandleDeleting"
+          ItemCommand="HandleCommand">
+    <ItemTemplate Context="Item">
+        <p>@Item.Name — @Item.Email</p>
+    </ItemTemplate>
+    <EditItemTemplate Context="Item">
+        <p>Editing: @Item.Name</p>
+    </EditItemTemplate>
+</FormView>
+
+@code {
+    private List<Customer> Customers = new();
+
+    private void HandleUpdating(FormViewUpdateEventArgs e)
+    {
+        // Validate and apply changes; set e.Cancel = true to abort
+    }
+
+    private void HandleUpdated(FormViewUpdatedEventArgs e)
+    {
+        // Post-update logic (e.g., refresh data, show notification)
+    }
+
+    private void HandleDeleting(FormViewDeleteEventArgs e)
+    {
+        // Perform delete; e.RowIndex gives the current position
+    }
+
+    private void HandleCommand(FormViewCommandEventArgs e)
+    {
+        // Fires for any command button — check e.CommandName
+    }
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/GridView/index.html b/site/DataControls/GridView/index.html new file mode 100644 index 000000000..ab664ed1c --- /dev/null +++ b/site/DataControls/GridView/index.html @@ -0,0 +1,5837 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GridView - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

GridView

+ +

The GridView component is meant to emulate the asp:GridView control in markup and is defined in the System.Web.UI.WebControls.GridView class

+

Features supported in Blazor

+
    +
  • Readonly grid
    • +
  • Bound, Button, Hyperlink, and Template columns
    • +
  • Paging - AllowPaging, PageSize, PageIndex, PageIndexChanged event
    • +
  • Sorting - AllowSorting, SortExpression, SortDirection, Sorting/Sorted events
    • +
  • Row Editing - EditIndex, RowEditing, RowUpdating, RowDeleting, RowCancelingEdit events
    • +
  • Selection - SelectedIndex, SelectedRow, SelectedValue, AutoGenerateSelectButton, SelectedIndexChanging/SelectedIndexChanged events
    • +
  • Style Sub-Components - RowStyle, AlternatingRowStyle, HeaderStyle, FooterStyle, SelectedRowStyle, EditRowStyle, EmptyDataRowStyle, PagerStyle
    • +
  • Display Properties - ShowHeader, ShowFooter, Caption, CaptionAlign, EmptyDataTemplate, GridLines, UseAccessibleHeader, CellPadding, CellSpacing, ShowHeaderWhenEmpty
    • +
  • ToolTip - tooltip text displayed on hover (renders as title attribute)
    • +
+

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
    • +
  • ItemType cascading - The ItemType parameter is automatically cascaded from the GridView to child columns. You only need to specify it once on the GridView, and all child columns (BoundField, TemplateField, HyperLinkField, ButtonField) will automatically infer the type. For backward compatibility, you can still explicitly specify ItemType on individual columns if desired.
    • +
  • Paging - When AllowPaging="true", the GridView automatically paginates the data source using Skip()/Take(). A numeric pager is rendered below the grid. The PageIndexChanged event fires with a PageChangedEventArgs containing NewPageIndex, OldPageIndex, TotalPages, StartRowIndex, and Cancel.
    • +
  • Sorting - When AllowSorting="true", column headers become clickable. You must handle the Sorting event to apply the sort to your data source. The Sorted event fires after the sort completes. Both events use GridViewSortEventArgs with SortExpression, SortDirection, and Cancel properties.
    • +
  • Row Editing - Set EditIndex to the zero-based row index to put a row in edit mode (-1 means no row is being edited). An auto-generated command column appears when at least one editing event callback is registered.
    • +
  • Selection - Set SelectedIndex to highlight a row. SelectedRow returns the data item for the selected row, and SelectedValue returns the DataKeyNames value. When AutoGenerateSelectButton="true", a "Select" link column is added automatically. The SelectedIndexChanging event fires before the selection changes (cancellable), and SelectedIndexChanged fires after.
    • +
  • Style Sub-Components - Use <RowStyle>, <AlternatingRowStyle>, <HeaderStyle>, <FooterStyle>, <SelectedRowStyle>, <EditRowStyle>, <EmptyDataRowStyle>, and <PagerStyle> child components to configure TableItemStyle properties (CssClass, BackColor, ForeColor, etc.) for each section of the grid.
    • +
  • Display Properties - ShowHeader and ShowFooter toggle header/footer rows. Caption and CaptionAlign add a <caption> element. GridLines controls table borders. UseAccessibleHeader renders <th> with scope="col". CellPadding and CellSpacing set table spacing. ShowHeaderWhenEmpty shows column headers even when the data source is empty. EmptyDataTemplate renders custom content when there are no data rows.
    • +
+
+

Differences from Web Forms

+
    +
  • PageIndexChanging is not implemented; use PageIndexChanged with the Cancel property instead.
    • +
  • PagerTemplate is not yet supported; only the built-in numeric pager is available.
    • +
  • Sorting does not automatically re-sort the data source; you must handle the Sorting event and apply the sort yourself.
    • +
  • SelectedIndexChanging uses GridViewSelectEventArgs with a Cancel property to prevent selection.
    • +
+
+

Syntax Comparison

+

Currently, not every syntax element of Web Forms GridView is supported. In the meantime, the following GridView in Blazor syntax will only include the implemented ones. Non-implemented elements will be included later.

+
+
+
+
<asp:GridView
+    AccessKey="string"
+    AllowPaging="True|False"
+    AllowSorting="True|False"
+    AutoGenerateColumns="True|False"
+    AutoGenerateDeleteButton="True|False"
+    AutoGenerateEditButton="True|False"
+    AutoGenerateSelectButton="True|False"
+    BackColor="color name|#dddddd"
+    BackImageUrl="uri"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    Caption="string"
+    CaptionAlign="NotSet|Top|Bottom|Left|Right"
+    CellPadding="integer"
+    CellSpacing="integer"
+    CssClass="string"
+    DataKeyNames="string"
+    DataMember="string"
+    DataSource="string"
+    DataSourceID="string"
+    EditIndex="integer"
+    EmptyDataText="string"
+    Enabled="True|False"
+    EnableSortingAndPagingCallbacks="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    GridLines="None|Horizontal|Vertical|Both"
+    Height="size"
+    HorizontalAlign="NotSet|Left|Center|Right|Justify"
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnDataBound="DataBound event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPageIndexChanged="PageIndexChanged event handler"
+    OnPageIndexChanging="PageIndexChanging event handler"
+    OnPreRender="PreRender event handler"
+    OnRowCancelingEdit="RowCancelingEdit event handler"
+    OnRowCommand="RowCommand event handler"
+    OnRowCreated="RowCreated event handler"
+    OnRowDataBound="RowDataBound event handler"
+    OnRowDeleted="RowDeleted event handler"
+    OnRowDeleting="RowDeleting event handler"
+    OnRowEditing="RowEditing event handler"
+    OnRowUpdated="RowUpdated event handler"
+    OnRowUpdating="RowUpdating event handler"
+    OnSelectedIndexChanged="SelectedIndexChanged event handler"
+    OnSelectedIndexChanging="SelectedIndexChanging event handler"
+    OnSorted="Sorted event handler"
+    OnSorting="Sorting event handler"
+    OnUnload="Unload event handler"
+    PageIndex="integer"
+    PagerSettings-FirstPageImageUrl="uri"
+    PagerSettings-FirstPageText="string"
+    PagerSettings-LastPageImageUrl="uri"
+    PagerSettings-LastPageText="string"
+    PagerSettings-Mode="NextPrevious|Numeric|NextPreviousFirstLast|
+        NumericFirstLast"
+    PagerSettings-NextPageImageUrl="uri"
+    PagerSettings-NextPageText="string"
+    PagerSettings-PageButtonCount="integer"
+    PagerSettings-Position="Bottom|Top|TopAndBottom"
+    PagerSettings-PreviousPageImageUrl="uri"
+    PagerSettings-PreviousPageText="string"
+    PagerSettings-Visible="True|False"
+    PageSize="integer"
+    RowHeaderColumn="string"
+    runat="server"
+    SelectedIndex="integer"
+    ShowFooter="True|False"
+    ShowHeader="True|False"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    ToolTip="string"
+    UseAccessibleHeader="True|False"
+    Visible="True|False"
+    Width="size"
+>
+        <AlternatingRowStyle />
+        <Columns>
+                <asp:BoundField
+                    AccessibleHeaderText="string"
+                    ApplyFormatInEditMode="True|False"
+                    ConvertEmptyStringToNull="True|False"
+                    DataField="string"
+                    DataFormatString="string"
+                    FooterText="string"
+                    HeaderImageUrl="uri"
+                    HeaderText="string"
+                    HtmlEncode="True|False"
+                    InsertVisible="True|False"
+                    NullDisplayText="string"
+                    ReadOnly="True|False"
+                    ShowHeader="True|False"
+                    SortExpression="string"
+                    Visible="True|False"
+>
+                        <ControlStyle />
+                        <FooterStyle />
+                        <HeaderStyle />
+                        <ItemStyle />
+                </asp:BoundField>
+                <asp:ButtonField
+                    AccessibleHeaderText="string"
+                    ButtonType="Button|Image|Link"
+                    CausesValidation="True|False"
+                    CommandName="string"
+                    DataTextField="string"
+                    DataTextFormatString="string"
+                    FooterText="string"
+                    HeaderImageUrl="uri"
+                    HeaderText="string"
+                    ImageUrl="uri"
+                    InsertVisible="True|False"
+                    ShowHeader="True|False"
+                    SortExpression="string"
+                    Text="string"
+                    ValidationGroup="string"
+                    Visible="True|False"
+>
+                        <ControlStyle />
+                        <FooterStyle />
+                        <HeaderStyle />
+                        <ItemStyle />
+                </asp:ButtonField>
+                <asp:CheckBoxField
+                    AccessibleHeaderText="string"
+                    DataField="string"
+                    FooterText="string"
+                    HeaderImageUrl="uri"
+                    HeaderText="string"
+                    InsertVisible="True|False"
+                    ReadOnly="True|False"
+                    ShowHeader="True|False"
+                    SortExpression="string"
+                    Text="string"
+                    Visible="True|False"
+>
+                        <ControlStyle />
+                        <FooterStyle />
+                        <HeaderStyle />
+                        <ItemStyle />
+                </asp:CheckBoxField>
+                <asp:CommandField
+                    AccessibleHeaderText="string"
+                    ButtonType="Button|Image|Link"
+                    CancelImageUrl="uri"
+                    CancelText="string"
+                    CausesValidation="True|False"
+                    DeleteImageUrl="uri"
+                    DeleteText="string"
+                    EditImageUrl="uri"
+                    EditText="string"
+                    FooterText="string"
+                    HeaderImageUrl="uri"
+                    HeaderText="string"
+                    InsertImageUrl="uri"
+                    InsertText="string"
+                    InsertVisible="True|False"
+                    NewImageUrl="uri"
+                    NewText="string"
+                    SelectImageUrl="uri"
+                    SelectText="string"
+                    ShowCancelButton="True|False"
+                    ShowDeleteButton="True|False"
+                    ShowEditButton="True|False"
+                    ShowHeader="True|False"
+                    ShowInsertButton="True|False"
+                    ShowSelectButton="True|False"
+                    SortExpression="string"
+                    UpdateImageUrl="uri"
+                    UpdateText="string"
+                    ValidationGroup="string"
+                    Visible="True|False"
+>
+                        <ControlStyle />
+                        <FooterStyle />
+                        <HeaderStyle />
+                        <ItemStyle />
+                </asp:CommandField>
+                <asp:DynamicField
+                    AccessibleHeaderText="string"
+                    ApplyFormatInEditMode="True|False"
+                    ConvertEmptyStringToNull="True|False"
+                    DataField="string"
+                    DataFormatString="string"
+                    FooterText="string"
+                    HeaderImageUrl="uri"
+                    HeaderText="string"
+                    HtmlEncode="True|False"
+                    InsertVisible="True|False"
+                    NullDisplayText="string"
+                    ShowHeader="True|False"
+                    UIHint="string"
+                    Visible="True|False"
+>
+                        <ControlStyle />
+                        <FooterStyle />
+                        <HeaderStyle />
+                        <ItemStyle />
+                </asp:DynamicField>
+                <asp:HyperLinkField
+                    AccessibleHeaderText="string"
+                    DataNavigateUrlFields="string"
+                    DataNavigateUrlFormatString="string"
+                    DataTextField="string"
+                    DataTextFormatString="string"
+                    FooterText="string"
+                    HeaderImageUrl="uri"
+                    HeaderText="string"
+                    InsertVisible="True|False"
+                    NavigateUrl="uri"
+                    ShowHeader="True|False"
+                    SortExpression="string"
+                    Target="string|_blank|_parent|_search|_self|_top"
+                    Text="string"
+                    Visible="True|False"
+>
+                        <ControlStyle />
+                        <FooterStyle />
+                        <HeaderStyle />
+                        <ItemStyle />
+                </asp:HyperLinkField>
+                <asp:ImageField
+                    AccessibleHeaderText="string"
+                    AlternateText="string"
+                    ConvertEmptyStringToNull="True|False"
+                    DataAlternateTextField="string"
+                    DataAlternateTextFormatString="string"
+                    DataImageUrlField="string"
+                    DataImageUrlFormatString="string"
+                    FooterText="string"
+                    HeaderImageUrl="uri"
+                    HeaderText="string"
+                    InsertVisible="True|False"
+                    NullDisplayText="string"
+                    NullImageUrl="uri"
+                    ReadOnly="True|False"
+                    ShowHeader="True|False"
+                    SortExpression="string"
+                    Visible="True|False"
+>
+                        <ControlStyle />
+                        <FooterStyle />
+                        <HeaderStyle />
+                        <ItemStyle />
+                </asp:ImageField>
+                <asp:TemplateField
+                    AccessibleHeaderText="string"
+                    ConvertEmptyStringToNull="True|False"
+                    FooterText="string"
+                    HeaderImageUrl="uri"
+                    HeaderText="string"
+                    InsertVisible="True|False"
+                    ShowHeader="True|False"
+                    SortExpression="string"
+                    Visible="True|False"
+>
+                            <ControlStyle />
+                            <FooterStyle />
+                            <HeaderStyle />
+                            <ItemStyle />
+                        <AlternatingItemTemplate>
+                            <!-- child controls -->
+                        </AlternatingItemTemplate>
+                        <EditItemTemplate>
+                            <!-- child controls -->
+                        </EditItemTemplate>
+                        <FooterTemplate>
+                            <!-- child controls -->
+                        </FooterTemplate>
+                        <HeaderTemplate>
+                            <!-- child controls -->
+                        </HeaderTemplate>
+                        <InsertItemTemplate>
+                            <!-- child controls -->
+                        </InsertItemTemplate>
+                        <ItemTemplate>
+                            <!-- child controls -->
+                        </ItemTemplate>
+                </asp:TemplateField>
+        </Columns>
+        <EditRowStyle />
+        <EmptyDataRowStyle />
+        <EmptyDataTemplate>
+            <!-- child controls -->
+        </EmptyDataTemplate>
+        <FooterStyle />
+        <HeaderStyle />
+        <PagerSettings
+            FirstPageImageUrl="uri"
+            FirstPageText="string"
+            LastPageImageUrl="uri"
+            LastPageText="string"
+            Mode="NextPrevious|Numeric|NextPreviousFirstLast|
+                NumericFirstLast"
+            NextPageImageUrl="uri"
+            NextPageText="string"
+            OnPropertyChanged="PropertyChanged event handler"
+            PageButtonCount="integer"
+            Position="Bottom|Top|TopAndBottom"
+            PreviousPageImageUrl="uri"
+            PreviousPageText="string"
+            Visible="True|False"
+        />
+        <PagerStyle />
+        <PagerTemplate>
+            <!-- child controls -->
+        </PagerTemplate>
+        <RowStyle />
+        <SelectedRowStyle />
+</asp:GridView>
+
+
+
+
<GridView
+    runat="server"
+    AllowPaging=bool
+    AllowSorting=bool
+    AutoGenerateColumns=bool
+    AutoGenerateSelectButton=bool
+    Caption=string
+    CaptionAlign=TableCaptionAlign
+    CellPadding=int
+    CellSpacing=int
+    CssClass=string
+    DataKeyNames=string
+    DataSource=IEnumerable
+    EditIndex=int
+    EmptyDataText=string
+    Enabled=bool
+    GridLines=GridLines
+    ID=string
+    Items=IEnumerable
+    ItemType=Type
+    OnDataBinding=EventCallBack
+    OnDataBound=EventCallBack
+    OnItemDataBound=EventCallBack
+    OnInit=EventCallBack
+    OnLoad=EventCallBack
+    OnPreRender=EventCallBack
+    OnUnload=EventCallBack
+    OnDisposed=EventCallBack
+    PageIndex=int
+    PageIndexChanged=EventCallBack<PageChangedEventArgs>
+    PageSize=int
+    RowCancelingEdit=EventCallBack<GridViewCancelEditEventArgs>
+    RowDeleting=EventCallBack<GridViewDeleteEventArgs>
+    RowEditing=EventCallBack<GridViewEditEventArgs>
+    RowUpdating=EventCallBack<GridViewUpdateEventArgs>
+    SelectedIndex=int
+    SelectedIndexChanged=EventCallBack<int>
+    SelectedIndexChanging=EventCallBack<GridViewSelectEventArgs>
+    SelectMethod=SelectHandler
+    ShowFooter=bool
+    ShowHeader=bool
+    ShowHeaderWhenEmpty=bool
+    SortDirection=SortDirection
+    SortExpression=string
+    Sorted=EventCallBack<GridViewSortEventArgs>
+    Sorting=EventCallBack<GridViewSortEventArgs>
+    TabIndex=int
+    UseAccessibleHeader=bool
+    Visible=bool
+>
+    <AlternatingRowStyle CssClass="string" BackColor="WebColor" ... />
+    <Columns>
+        <!-- Note: ItemType is optional on columns and will be automatically 
+             inferred from the parent GridView. You can still explicitly 
+             specify ItemType on individual columns for clarity if desired. -->
+        <BoundField
+                    DataField=string
+                    DataFormatString=string
+                    HeaderText=string
+                    ItemType=Type (optional, inferred from parent)
+                    Visible=bool
+        >
+        </BoundField>
+        <HyperLinkField
+            AccessibleHeaderText="string"
+            DataNavigateUrlFields="string"
+            DataNavigateUrlFormatString="string"
+            DataTextField="string"
+            DataTextFormatString="string"
+            HeaderText="string"
+            ItemType=Type (optional, inferred from parent)
+            NavigateUrl="uri"
+            Target="string|_blank|_parent|_search|_self|_top"
+            Text="string"
+            Visible="True|False">
+        </HyperLinkField>
+        <TemplateField
+                 HeaderText=string
+                 ItemType=Type (optional, inferred from parent)
+                 Visible=bool
+        >
+            <ItemTemplate Context="Item">
+                <!-- Child Content -->
+            <ItemTemplate>
+        </TemplateField>
+    </Columns>
+    <EditRowStyle CssClass="string" BackColor="WebColor" ... />
+    <EmptyDataRowStyle CssClass="string" BackColor="WebColor" ... />
+    <EmptyDataTemplate>
+        <!-- Custom content when no data rows -->
+    </EmptyDataTemplate>
+    <FooterStyle CssClass="string" BackColor="WebColor" ... />
+    <HeaderStyle CssClass="string" BackColor="WebColor" ... />
+    <PagerStyle CssClass="string" BackColor="WebColor" ... />
+    <RowStyle CssClass="string" BackColor="WebColor" ... />
+    <SelectedRowStyle CssClass="string" BackColor="WebColor" ... />
+</GridView>
+
+
+
+
+

Examples

+

Basic Paging

+
@* GridView with paging enabled, 5 items per page *@
+<GridView DataSource="@Products"
+          ItemType="Product"
+          AllowPaging="true"
+          PageSize="5"
+          PageIndexChanged="HandlePageChanged"
+          AutoGenerateColumns="true" />
+
+<p>Page @(currentPageIndex + 1)</p>
+
+@code {
+    private List<Product> Products = new();
+    private int currentPageIndex = 0;
+
+    private void HandlePageChanged(PageChangedEventArgs e)
+    {
+        currentPageIndex = e.NewPageIndex;
+    }
+}
+
+

Sorting

+
@* GridView with sortable columns *@
+<GridView DataSource="@SortedProducts"
+          ItemType="Product"
+          AllowSorting="true"
+          SortExpression="@sortExpression"
+          SortDirection="@sortDirection"
+          Sorting="HandleSorting">
+    <Columns>
+        <BoundField DataField="Name" HeaderText="Name" />
+        <BoundField DataField="Price" HeaderText="Price" DataFormatString="{0:C}" />
+    </Columns>
+</GridView>
+
+@code {
+    private List<Product> Products = new();
+    private string sortExpression = "";
+    private SortDirection sortDirection = SortDirection.Ascending;
+
+    private IEnumerable<Product> SortedProducts => sortExpression switch
+    {
+        "Name" => sortDirection == SortDirection.Ascending
+            ? Products.OrderBy(p => p.Name)
+            : Products.OrderByDescending(p => p.Name),
+        "Price" => sortDirection == SortDirection.Ascending
+            ? Products.OrderBy(p => p.Price)
+            : Products.OrderByDescending(p => p.Price),
+        _ => Products
+    };
+
+    private void HandleSorting(GridViewSortEventArgs e)
+    {
+        sortExpression = e.SortExpression;
+        sortDirection = e.SortDirection;
+    }
+}
+
+

Row Editing

+
@* GridView with inline edit, update, delete, and cancel *@
+<GridView DataSource="@Products"
+          ItemType="Product"
+          EditIndex="@editIndex"
+          RowEditing="HandleEdit"
+          RowUpdating="HandleUpdate"
+          RowDeleting="HandleDelete"
+          RowCancelingEdit="HandleCancelEdit">
+    <Columns>
+        <BoundField DataField="Name" HeaderText="Name" />
+        <BoundField DataField="Price" HeaderText="Price" DataFormatString="{0:C}" />
+    </Columns>
+</GridView>
+
+@code {
+    private List<Product> Products = new();
+    private int editIndex = -1;
+
+    private void HandleEdit(GridViewEditEventArgs e)
+    {
+        editIndex = e.NewEditIndex;
+    }
+
+    private void HandleUpdate(GridViewUpdateEventArgs e)
+    {
+        // Apply changes to Products[e.RowIndex]
+        editIndex = -1;
+    }
+
+    private void HandleDelete(GridViewDeleteEventArgs e)
+    {
+        Products.RemoveAt(e.RowIndex);
+        editIndex = -1;
+    }
+
+    private void HandleCancelEdit(GridViewCancelEditEventArgs e)
+    {
+        editIndex = -1;
+    }
+}
+
+

Paging with Sorting

+
@* Combining paging and sorting *@
+<GridView DataSource="@SortedProducts"
+          ItemType="Product"
+          AllowPaging="true"
+          PageSize="10"
+          PageIndexChanged="HandlePageChanged"
+          AllowSorting="true"
+          SortExpression="@sortExpression"
+          SortDirection="@sortDirection"
+          Sorting="HandleSorting">
+    <Columns>
+        <BoundField DataField="Name" HeaderText="Name" />
+        <BoundField DataField="Price" HeaderText="Price" DataFormatString="{0:C}" />
+    </Columns>
+</GridView>
+
+@code {
+    private List<Product> Products = new();
+    private int currentPageIndex = 0;
+    private string sortExpression = "";
+    private SortDirection sortDirection = SortDirection.Ascending;
+
+    private IEnumerable<Product> SortedProducts => sortExpression switch
+    {
+        "Name" => sortDirection == SortDirection.Ascending
+            ? Products.OrderBy(p => p.Name)
+            : Products.OrderByDescending(p => p.Name),
+        "Price" => sortDirection == SortDirection.Ascending
+            ? Products.OrderBy(p => p.Price)
+            : Products.OrderByDescending(p => p.Price),
+        _ => Products
+    };
+
+    private void HandlePageChanged(PageChangedEventArgs e)
+    {
+        currentPageIndex = e.NewPageIndex;
+    }
+
+    private void HandleSorting(GridViewSortEventArgs e)
+    {
+        sortExpression = e.SortExpression;
+        sortDirection = e.SortDirection;
+    }
+}
+
+

Row Selection

+
@* GridView with row selection and auto-generated select button *@
+<GridView DataSource="@Products"
+          ItemType="Product"
+          AutoGenerateSelectButton="true"
+          SelectedIndex="@selectedIndex"
+          SelectedIndexChanged="HandleSelectionChanged">
+    <Columns>
+        <BoundField DataField="Name" HeaderText="Name" />
+        <BoundField DataField="Price" HeaderText="Price" DataFormatString="{0:C}" />
+    </Columns>
+    <SelectedRowStyle CssClass="selected-row" BackColor="LightBlue" />
+</GridView>
+
+@if (SelectedProduct is not null)
+{
+    <p>Selected: @SelectedProduct.Name</p>
+}
+
+@code {
+    private List<Product> Products = new();
+    private int selectedIndex = -1;
+
+    private Product? SelectedProduct => selectedIndex >= 0 && selectedIndex < Products.Count
+        ? Products[selectedIndex]
+        : null;
+
+    private void HandleSelectionChanged(int newIndex)
+    {
+        selectedIndex = newIndex;
+    }
+}
+
+

Selection with Cancellation

+
@* Prevent selection of inactive items *@
+<GridView DataSource="@Products"
+          ItemType="Product"
+          AutoGenerateSelectButton="true"
+          SelectedIndex="@selectedIndex"
+          SelectedIndexChanging="HandleSelecting"
+          SelectedIndexChanged="HandleSelected">
+    <Columns>
+        <BoundField DataField="Name" HeaderText="Name" />
+        <BoundField DataField="IsActive" HeaderText="Active" />
+    </Columns>
+</GridView>
+
+@code {
+    private List<Product> Products = new();
+    private int selectedIndex = -1;
+
+    private void HandleSelecting(GridViewSelectEventArgs e)
+    {
+        // Cancel selection of inactive products
+        if (!Products[e.NewSelectedIndex].IsActive)
+        {
+            e.Cancel = true;
+        }
+    }
+
+    private void HandleSelected(int newIndex)
+    {
+        selectedIndex = newIndex;
+    }
+}
+
+

Style Sub-Components

+
@* GridView with comprehensive styling *@
+<GridView DataSource="@Products"
+          ItemType="Product"
+          AutoGenerateColumns="true"
+          ShowHeader="true"
+          ShowFooter="true"
+          GridLines="Both"
+          CellPadding="4"
+          UseAccessibleHeader="true"
+          Caption="Product Inventory"
+          CaptionAlign="Top">
+    <HeaderStyle CssClass="grid-header" BackColor="DarkBlue" ForeColor="White" />
+    <RowStyle CssClass="grid-row" BackColor="White" />
+    <AlternatingRowStyle CssClass="grid-alt-row" BackColor="LightGray" />
+    <SelectedRowStyle CssClass="grid-selected" BackColor="LightBlue" />
+    <FooterStyle CssClass="grid-footer" BackColor="DarkBlue" ForeColor="White" />
+    <EditRowStyle CssClass="grid-edit" BackColor="LightYellow" />
+    <PagerStyle CssClass="grid-pager" />
+</GridView>
+
+

Empty Data Template

+
@* GridView with custom empty data display *@
+<GridView DataSource="@FilteredProducts"
+          ItemType="Product"
+          AutoGenerateColumns="true"
+          ShowHeaderWhenEmpty="true"
+          EmptyDataText="No products found.">
+    <EmptyDataTemplate>
+        <div class="empty-message">
+            <p>No products match your filter criteria.</p>
+            <Button Text="Clear Filters" OnClick="ClearFilters" />
+        </div>
+    </EmptyDataTemplate>
+    <EmptyDataRowStyle CssClass="empty-row" ForeColor="Gray" />
+</GridView>
+
+@code {
+    private List<Product> FilteredProducts = new();
+
+    private void ClearFilters()
+    {
+        // Reset filters and reload data
+    }
+}
+
+

Selection Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
SelectedIndexint-1Zero-based index of the selected row. -1 = no selection.
SelectedRowItemTypedefaultRead-only. Returns the data item for the selected row.
SelectedValueobjectnullRead-only. Returns the DataKeyNames value of the selected row.
AutoGenerateSelectButtonboolfalseWhen true, adds a "Select" link column.
SelectedIndexChangingEventCallback<GridViewSelectEventArgs>—Fires before selection changes. Set Cancel = true to prevent.
SelectedIndexChangedEventCallback<int>—Fires after the selected row changes.
+

Style Sub-Components Reference

+

All style sub-components use TableItemStyle which supports:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
CssClassstringCSS class name
BackColorWebColorBackground color
ForeColorWebColorText color
BorderColorWebColorBorder color
BorderStyleBorderStyleBorder style (Solid, Dashed, etc.)
BorderWidthUnitBorder width
FontFontInfoFont settings
HeightUnitRow height
WidthUnitRow width
HorizontalAlignHorizontalAlignContent alignment
WrapboolWhether content wraps
+

Available style sub-components:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentApplied To
<RowStyle>All data rows
<AlternatingRowStyle>Even-numbered data rows
<HeaderStyle>Header row
<FooterStyle>Footer row
<SelectedRowStyle>Currently selected row
<EditRowStyle>Row being edited
<EmptyDataRowStyle>Empty data row
<PagerStyle>Pager row
+

Display Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
ShowHeaderbooltrueShow/hide the header row
ShowFooterboolfalseShow/hide the footer row
CaptionstringnullCaption text above the table
CaptionAlignTableCaptionAlignNotSetCaption alignment (Top, Bottom, Left, Right)
GridLinesGridLinesNoneTable gridlines (None, Horizontal, Vertical, Both)
UseAccessibleHeaderboolfalseRender <th scope="col"> instead of <td>
CellPaddingint-1Cell padding in pixels (-1 = not set)
CellSpacingint-1Cell spacing in pixels (-1 = not set)
ShowHeaderWhenEmptyboolfalseShow column headers when data source is empty
EmptyDataTextstringnullText shown when data source is empty
EmptyDataTemplateRenderFragmentnullCustom template shown when data source is empty
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/ListView/index.html b/site/DataControls/ListView/index.html new file mode 100644 index 000000000..30f5ed2e0 --- /dev/null +++ b/site/DataControls/ListView/index.html @@ -0,0 +1,5194 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ListView - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ListView

+

The ListView component is meant to emulate the asp:ListView control in markup and is defined in the System.Web.UI.WebControls.ListView class

+

Usage Notes | Syntax Comparison | CRUD Operations

+

Features supported in Blazor

+
    +
  • Alternating Item Templates
    • +
  • Alternating Item Styles
    • +
  • Empty Data Template
    • +
  • Empty Item Template
    • +
  • Grouping
    • +
  • Item Templates
    • +
  • Item Styles
    • +
  • Model Binding
    • +
  • OnSelect Method
    • +
  • LayoutTemplate
    • +
  • DataBinder within the ItemTemplate and AlternatingItemTemplate
    • +
  • ListViewItem and ListViewDataItem for event handling
    • +
  • CRUD Operations (Edit, Delete, Insert, Update, Cancel)
    • +
  • EditItemTemplate
    • +
  • InsertItemTemplate
    • +
  • EditIndex
    • +
  • InsertItemPosition
    • +
+
Back to top
+

ListViewItem and ListViewDataItem

+

The OnItemDataBound event provides a ListViewItemEventArgs object that contains a ListViewItem instance. For data items, this will be a ListViewDataItem object with the following properties:

+
    +
  • ItemType - The type of item (DataItem, InsertItem, or EmptyItem)
    • +
  • DisplayIndex - The position of the item as displayed in the ListView
    • +
  • DataItemIndex - The index of the data item in the underlying data source
    • +
  • DataItem - The underlying data object bound to this item
    • +
+

Example:

+
void ItemDataBound(ListViewItemEventArgs e)
+{
+    if (e.Item.ItemType == ListViewItemType.DataItem)
+    {
+        var dataItem = (ListViewDataItem)e.Item;
+        var widget = (Widget)dataItem.DataItem;
+        // Access widget.Name, widget.Price, etc.
+    }
+}
+
+
Back to top
+

Usage Notes

+
    +
  • 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
+

Syntax Comparison

+
+
+
+
<asp:ListView  
+    ConvertEmptyStringToNull="True|False"  
+    DataKeyNames="string"  
+    DataMember="string"  
+    DataSource="string"  
+    DataSourceID="string"  
+    EditIndex="integer"  
+    Enabled="True|False"  
+    EnableTheming="True|False"  
+    EnableViewState="True|False"  
+    GroupPlaceholderID="string"  
+    GroupItemCount="integer"  
+    ID="string"  
+    InsertItemPosition="None|FirstItem|LastItem"  
+    ItemPlaceholderID="string"  
+    OnDataBinding="DataBinding event handler"  
+    OnDataBound="DataBound event handler"  
+    OnDisposed="Disposed event handler"  
+    OnInit="Init event handler"  
+    OnItemCanceling="ItemCanceling event handler"  
+    OnItemCommand="ItemCommand event handler"  
+    OnItemCreated="ItemCreated event handler"  
+    OnItemDataBound="ItemDataBound event handler"  
+    OnItemDeleted="ItemDeleted event handler"  
+    OnItemDeleting="ItemDeleting event handler"  
+    OnItemEditing="ItemEditing event handler"  
+    OnItemInserted="ItemInserted event handler"  
+    OnItemInserting="ItemInserting event handler"  
+    OnItemUpdated="ItemUpdated event handler"  
+    OnItemUpdating="ItemUpdating event handler"  
+    OnLayoutCreated="LayoutCreated event handler"  
+    OnLoad="Load event handler"  
+    OnPagePropertiesChanged="PagePropertiesChanged event handler"  
+    OnPagePropertiesChanging="PagePropertiesChanging event handler"  
+    OnPreRender="PreRender event handler"  
+    OnSelectedIndexChanged="SelectedIndexChanged event handler"  
+    OnSelectedIndexChanging="SelectedIndexChanging event handler"  
+    OnSorted="Sorted event handler"  
+    OnSorting="Sorting event handler"  
+    OnUnload="Unload event handler"  
+    runat="server"  
+    SelectedIndex="integer"  
+    SkinID="string"  
+    Style="string"  
+    Visible="True|False">  
+    <AlternatingItemTemplate>  
+        <!-- child controls -->  
+    </AlternatingItemTemplate>  
+    <EditItemTemplate>  
+        <!-- child controls -->  
+    </EditItemTemplate>  
+    <EmptyDataTemplate>  
+        <!-- child controls -->  
+    </EmptyDataTemplate>  
+    <EmptyItemTemplate>  
+        <!-- child controls -->  
+    </EmptyItemTemplate>  
+    <GroupSeparatorTemplate>  
+        <!-- child controls -->  
+    </GroupSeparatorTemplate>  
+    <GroupTemplate>  
+        <!-- child controls -->  
+    </GroupTemplate>  
+    <InsertItemTemplate>  
+        <!-- child controls -->  
+    </InsertItemTemplate>  
+    <ItemSeparatorTemplate>  
+        <!-- child controls -->  
+    </ItemSeparatorTemplate>  
+    <ItemTemplate>  
+        <!-- child controls -->  
+    </ItemTemplate>  
+    <LayoutTemplate>  
+            <!-- child controls -->  
+    </LayoutTemplate>  
+    <SelectedItemTemplate>  
+        <!-- child controls -->  
+    </SelectedItemTemplate>  
+</asp:ListView>
+
+
+
+
<ListView Context="Item"
+          ItemType="Widget"
+          EditIndex="@editIndex"
+          InsertItemPosition="InsertItemPosition.LastItem"
+          ItemEditing="OnItemEditing"
+          ItemUpdating="OnItemUpdating"
+          ItemCanceling="OnItemCanceling"
+          ItemDeleting="OnItemDeleting"
+          ItemInserting="OnItemInserting">
+    <ItemTemplate>
+        <tr>
+            <td>@Item.Name</td>
+            <td>
+                <button @onclick="() => listView.HandleCommand("edit", null, index)">Edit</button>
+                <button @onclick="() => listView.HandleCommand("delete", null, index)">Delete</button>
+            </td>
+        </tr>
+    </ItemTemplate>
+    <EditItemTemplate>
+        <tr>
+            <td><input @bind="editName" /></td>
+            <td>
+                <button @onclick="() => listView.HandleCommand("update", null, editIndex)">Update</button>
+                <button @onclick="() => listView.HandleCommand("cancel", null, editIndex)">Cancel</button>
+            </td>
+        </tr>
+    </EditItemTemplate>
+    <InsertItemTemplate>
+        <tr>
+            <td><input @bind="newName" /></td>
+            <td>
+                <button @onclick="() => listView.HandleCommand("insert", null, 0)">Insert</button>
+            </td>
+        </tr>
+    </InsertItemTemplate>
+    <EmptyDataTemplate>No items available.</EmptyDataTemplate>
+</ListView>
+
+
+
+
+
Back to top
+

CRUD Operations

+

The ListView supports full Create, Read, Update, and Delete operations through a set of command events. Use HandleCommand on the ListView reference to trigger operations.

+

Events

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventEventArgsDescription
ItemEditingListViewEditEventArgsFires when an Edit command is requested. Set NewEditIndex to control which item enters edit mode.
ItemUpdatingListViewUpdateEventArgsFires when an Update command is requested. ItemIndex identifies the item being updated.
ItemCancelingListViewCancelEventArgsFires when a Cancel command is requested.
ItemDeletingListViewDeleteEventArgsFires before an item is deleted. Set Cancel = true to prevent deletion.
ItemDeletedListViewDeletedEventArgsFires after a delete operation completes.
ItemInsertingListViewInsertEventArgsFires before an item is inserted. Set Cancel = true to prevent insertion.
ItemInsertedListViewInsertedEventArgsFires after an insert operation completes.
+

EditItemTemplate

+

When EditIndex is set to a valid item index, the EditItemTemplate is rendered for that item instead of the ItemTemplate. Set EditIndex = -1 to exit edit mode.

+

InsertItemTemplate

+

The InsertItemTemplate renders an insert row when InsertItemPosition is set to FirstItem or LastItem. Set to None (default) to hide the insert row.

+

Migration Example

+
+
+
+
<asp:ListView ID="lvItems" runat="server"
+    OnItemEditing="lvItems_ItemEditing"
+    OnItemUpdating="lvItems_ItemUpdating"
+    OnItemDeleting="lvItems_ItemDeleting"
+    OnItemInserting="lvItems_ItemInserting"
+    InsertItemPosition="LastItem">
+    <ItemTemplate>
+        <tr>
+            <td><%# Eval("Name") %></td>
+            <td>
+                <asp:Button runat="server" CommandName="Edit" Text="Edit" />
+                <asp:Button runat="server" CommandName="Delete" Text="Delete" />
+            </td>
+        </tr>
+    </ItemTemplate>
+    <EditItemTemplate>
+        <tr>
+            <td><asp:TextBox ID="txtName" runat="server" Text='<%# Bind("Name") %>' /></td>
+            <td>
+                <asp:Button runat="server" CommandName="Update" Text="Update" />
+                <asp:Button runat="server" CommandName="Cancel" Text="Cancel" />
+            </td>
+        </tr>
+    </EditItemTemplate>
+</asp:ListView>
+
+
+
+
<ListView @ref="listView" Context="Item" ItemType="Widget"
+    EditIndex="@editIndex"
+    InsertItemPosition="InsertItemPosition.LastItem"
+    ItemEditing="OnItemEditing"
+    ItemUpdating="OnItemUpdating"
+    ItemDeleting="OnItemDeleting"
+    ItemInserting="OnItemInserting">
+    <ItemTemplate>
+        <tr>
+            <td>@Item.Name</td>
+            <td>
+                <button @onclick="() => listView.HandleCommand("edit", null, idx)">Edit</button>
+                <button @onclick="() => listView.HandleCommand("delete", null, idx)">Delete</button>
+            </td>
+        </tr>
+    </ItemTemplate>
+    <EditItemTemplate>
+        <tr>
+            <td><input @bind="editName" /></td>
+            <td>
+                <button @onclick="() => listView.HandleCommand("update", null, editIndex)">Update</button>
+                <button @onclick="() => listView.HandleCommand("cancel", null, editIndex)">Cancel</button>
+            </td>
+        </tr>
+    </EditItemTemplate>
+</ListView>
+
+
+
+
+
Back to top
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/PagerSettings/index.html b/site/DataControls/PagerSettings/index.html new file mode 100644 index 000000000..09ee1f6ff --- /dev/null +++ b/site/DataControls/PagerSettings/index.html @@ -0,0 +1,5049 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + PagerSettings - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

PagerSettings

+

The PagerSettings class represents the properties of paging controls in data-bound components that support pagination. It is a shared sub-component used by FormView, DetailsView, and GridView to configure pager button behavior, text, images, and position.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.pagersettings?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • Mode — Pager button style: Numeric, NextPrevious, NextPreviousFirstLast, NumericFirstLast
    • +
  • PageButtonCount — Number of numeric page buttons to display (default: 10)
    • +
  • FirstPageText / LastPageText — Text for First and Last page buttons
    • +
  • NextPageText / PreviousPageText — Text for Next and Previous page buttons
    • +
  • FirstPageImageUrl / LastPageImageUrl — Image URLs for First and Last page buttons
    • +
  • NextPageImageUrl / PreviousPageImageUrl — Image URLs for Next and Previous page buttons
    • +
  • Position — Pager placement: Bottom (default), Top, or TopAndBottom
    • +
  • Visible — Show or hide the pager (default: true)
    • +
+

Blazor Notes

+
    +
  • PagerSettings is not a standalone component — it is configured as a child element of a data-bound control (FormView, DetailsView, GridView).
    • +
  • In Blazor, PagerSettings is specified using a <PagerSettings> child element inside the parent component, similar to how style sub-components work.
    • +
  • The PagerButtons enum replaces the Web Forms PagerButtons enumeration with identical values.
    • +
+

Web Forms Features NOT Supported

+
    +
  • OnPropertyChanged event — Not applicable in Blazor's reactive model
    • +
  • RenderNonBreakingSpacesBetweenControls — Not implemented
    • +
+

Syntax Comparison

+
+
+
+

In Web Forms, PagerSettings is configured as a child element or via dash-separated attributes:

+
<asp:FormView ID="FormView1" runat="server" AllowPaging="True">
+    <PagerSettings
+        Mode="NextPreviousFirstLast"
+        FirstPageText="First"
+        LastPageText="Last"
+        NextPageText="Next"
+        PreviousPageText="Previous"
+        PageButtonCount="10"
+        Position="Bottom"
+        Visible="True"
+        FirstPageImageUrl="~/images/first.gif"
+        LastPageImageUrl="~/images/last.gif"
+        NextPageImageUrl="~/images/next.gif"
+        PreviousPageImageUrl="~/images/prev.gif"
+    />
+    <ItemTemplate>
+        <!-- content -->
+    </ItemTemplate>
+</asp:FormView>
+
+

Or using dash-separated attributes on the parent control:

+
<asp:GridView ID="GridView1" runat="server"
+    AllowPaging="True"
+    PagerSettings-Mode="NumericFirstLast"
+    PagerSettings-FirstPageText="First"
+    PagerSettings-LastPageText="Last"
+    PagerSettings-PageButtonCount="5"
+    PagerSettings-Position="TopAndBottom" />
+
+
+
+
<FormView DataSource="@Items" ItemType="Product" AllowPaging="true">
+    <PagerSettings
+        Mode="PagerButtons.NextPreviousFirstLast"
+        FirstPageText="First"
+        LastPageText="Last"
+        NextPageText="Next >"
+        PreviousPageText="< Previous"
+        PageButtonCount="10"
+        Position="PagerPosition.Bottom"
+        Visible="true" />
+    <ItemTemplate Context="Item">
+        <!-- content -->
+    </ItemTemplate>
+</FormView>
+
+
+
+
+

Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
ModePagerButtonsNumericThe style of pager buttons to display
PageButtonCountint10Number of numeric page buttons shown
FirstPageTextstring"..."Text for the First page button
LastPageTextstring"..."Text for the Last page button
NextPageTextstring">"Text for the Next page button
PreviousPageTextstring"<"Text for the Previous page button
FirstPageImageUrlstringnullImage URL for the First page button
LastPageImageUrlstringnullImage URL for the Last page button
NextPageImageUrlstringnullImage URL for the Next page button
PreviousPageImageUrlstringnullImage URL for the Previous page button
PositionPagerPositionBottomWhere to display the pager
VisiblebooltrueWhether the pager is displayed
+

PagerButtons Enum

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
PagerButtons.NextPreviousDisplays Next and Previous buttons
PagerButtons.NumericDisplays numeric page buttons (default)
PagerButtons.NextPreviousFirstLastDisplays Next, Previous, First, and Last buttons
PagerButtons.NumericFirstLastDisplays numeric page buttons with First and Last buttons
+

PagerPosition Enum

+ + + + + + + + + + + + + + + + + + + + + +
ValueDescription
PagerPosition.BottomPager at the bottom of the control (default)
PagerPosition.TopPager at the top of the control
PagerPosition.TopAndBottomPager at both top and bottom
+

Usage with Parent Controls

+

FormView

+
<FormView DataSource="@Employees" ItemType="Employee" AllowPaging="true">
+    <PagerSettings Mode="PagerButtons.NumericFirstLast"
+                   FirstPageText="« First"
+                   LastPageText="Last »"
+                   PageButtonCount="5" />
+    <ItemTemplate Context="Item">
+        <p><strong>@Item.Name</strong> — @Item.Title</p>
+    </ItemTemplate>
+</FormView>
+
+

DetailsView

+
<DetailsView ItemType="Product" Items="@Products" AllowPaging="true">
+    <PagerSettings Mode="PagerButtons.NextPreviousFirstLast"
+                   FirstPageText="First"
+                   LastPageText="Last"
+                   NextPageText="Next >"
+                   PreviousPageText="< Prev"
+                   Position="PagerPosition.TopAndBottom" />
+</DetailsView>
+
+

Migration Notes

+
    +
  1. Remove dash-separated attributes — Web Forms PagerSettings-Mode="Numeric" becomes a child <PagerSettings Mode="PagerButtons.Numeric" /> element
    2. +
  2. Use enum values — Web Forms string values like "NextPreviousFirstLast" become PagerButtons.NextPreviousFirstLast
    3. +
  3. Position enum — Web Forms Position="TopAndBottom" becomes Position="PagerPosition.TopAndBottom"
    4. +
  4. Image URLs — Image URL properties work the same way but should use Blazor static asset paths instead of ~/ server-relative paths
    5. +
+
+
+
+
<asp:GridView ID="gv1" runat="server" AllowPaging="True">
+    <PagerSettings
+        Mode="NumericFirstLast"
+        FirstPageText="First"
+        LastPageText="Last"
+        Position="TopAndBottom" />
+</asp:GridView>
+
+
+
+
<GridView ItemType="Product" Items="@Products" AllowPaging="true">
+    <PagerSettings
+        Mode="PagerButtons.NumericFirstLast"
+        FirstPageText="First"
+        LastPageText="Last"
+        Position="PagerPosition.TopAndBottom" />
+</GridView>
+
+
+
+
+

See Also

+
    +
  • FormView — Single-record view with paging support
    • +
  • DetailsView — Single-record detail view with paging support
    • +
  • GridView — Multi-record tabular display with paging support
    • +
  • DataPager — Standalone paging control for ListView
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/DataControls/Repeater/index.html b/site/DataControls/Repeater/index.html new file mode 100644 index 000000000..deaeef3f0 --- /dev/null +++ b/site/DataControls/Repeater/index.html @@ -0,0 +1,4953 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Repeater - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Repeater

+

The Repeater component emulates the ASP.NET Web Forms asp:Repeater control. It provides a lightweight, template-driven way to display repeating data without imposing any HTML structure. Unlike GridView or DataList, the Repeater produces no wrapper markup — you have full control over the rendered output.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.repeater?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • ItemTemplate — Template for each data item
    • +
  • AlternatingItemTemplate — Template for alternating items
    • +
  • HeaderTemplate — Rendered once before all items
    • +
  • FooterTemplate — Rendered once after all items
    • +
  • SeparatorTemplate — Rendered between each item
    • +
  • ItemType — Strongly typed data binding
    • +
  • Items / SelectMethod — Data source binding
    • +
  • Context attribute — Access current item as @Item for Web Forms compatibility
    • +
+

Web Forms Features NOT Supported

+
    +
  • DataSourceID — Blazor does not use server-side data source controls; pass data directly via Items or SelectMethod
    • +
  • EnableViewState — Not needed; Blazor preserves component state natively
    • +
  • EnableTheming / SkinID — Not applicable to Blazor
    • +
+

Syntax Comparison

+
+
+
+
<asp:Repeater
+    DataMember="string"
+    DataSource="string"
+    DataSourceID="string"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnItemCommand="ItemCommand event handler"
+    OnItemCreated="ItemCreated event handler"
+    OnItemDataBound="ItemDataBound event handler"
+    runat="server"
+    Visible="True|False"
+>
+    <HeaderTemplate>
+        <!-- header content -->
+    </HeaderTemplate>
+    <ItemTemplate>
+        <!-- item content -->
+    </ItemTemplate>
+    <AlternatingItemTemplate>
+        <!-- alternating item content -->
+    </AlternatingItemTemplate>
+    <SeparatorTemplate>
+        <!-- separator content -->
+    </SeparatorTemplate>
+    <FooterTemplate>
+        <!-- footer content -->
+    </FooterTemplate>
+</asp:Repeater>
+
+
+
+
<Repeater Items="@dataSource" ItemType="MyItem" Context="Item">
+    <HeaderTemplate>
+        <!-- header content -->
+    </HeaderTemplate>
+    <ItemTemplate>
+        @Item.Name — @Item.Value
+    </ItemTemplate>
+    <AlternatingItemTemplate>
+        <em>@Item.Name — @Item.Value</em>
+    </AlternatingItemTemplate>
+    <SeparatorTemplate>
+        <hr />
+    </SeparatorTemplate>
+    <FooterTemplate>
+        <!-- footer content -->
+    </FooterTemplate>
+</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)
    • +
+
+

No Wrapper Markup

+

The Repeater produces no additional HTML wrapper elements. The output is exactly what you define in your templates. This makes it ideal for generating custom lists, navigation menus, or any repeating structure.

+
+

Examples

+

Product List

+
<Repeater Items="@products" ItemType="Product" Context="Item">
+    <HeaderTemplate>
+        <h2>Product List</h2>
+        <ul>
+    </HeaderTemplate>
+    <ItemTemplate>
+        <li>@Item.Name — @Item.Price.ToString("C")</li>
+    </ItemTemplate>
+    <FooterTemplate>
+        </ul>
+        <p>Total: @products.Count items</p>
+    </FooterTemplate>
+</Repeater>
+
+@code {
+    private var products = new List<Product>
+    {
+        new Product { Name = "Widget", Price = 9.99m },
+        new Product { Name = "Gadget", Price = 24.99m },
+        new Product { Name = "Gizmo", Price = 14.99m }
+    };
+}
+
+

Table with Alternating Rows

+
<Repeater Items="@employees" ItemType="Employee" Context="Item">
+    <HeaderTemplate>
+        <table class="table">
+            <thead><tr><th>Name</th><th>Department</th></tr></thead>
+            <tbody>
+    </HeaderTemplate>
+    <ItemTemplate>
+        <tr>
+            <td>@Item.Name</td>
+            <td>@Item.Department</td>
+        </tr>
+    </ItemTemplate>
+    <AlternatingItemTemplate>
+        <tr style="background-color: #f5f5f5;">
+            <td>@Item.Name</td>
+            <td>@Item.Department</td>
+        </tr>
+    </AlternatingItemTemplate>
+    <FooterTemplate>
+            </tbody>
+        </table>
+    </FooterTemplate>
+</Repeater>
+
+ +
<Repeater Items="@menuItems" ItemType="MenuItem" Context="Item">
+    <ItemTemplate>
+        <a href="@Item.Url">@Item.Label</a>
+    </ItemTemplate>
+    <SeparatorTemplate>
+        <span> | </span>
+    </SeparatorTemplate>
+</Repeater>
+
+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:Repeater> to <Repeater>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Add ItemType — Specify the data item type: ItemType="Product"
    4. +
  4. Add Context="Item" — To use @Item in templates (matching Web Forms <%# Container.DataItem %>)
    5. +
  5. Replace data binding — Change DataSourceID or code-behind DataSource/DataBind() to Items="@collection" or SelectMethod
    6. +
  6. Replace <%# Eval("Name") %> — Use @Item.Name with strongly typed binding
    7. +
  7. Templates are identical — HeaderTemplate, ItemTemplate, AlternatingItemTemplate, SeparatorTemplate, FooterTemplate all work the same way
    8. +
+

Migration Example

+
+
+
+
<asp:Repeater ID="rptProducts" DataSourceID="SqlDS" runat="server">
+    <HeaderTemplate>
+        <ul>
+    </HeaderTemplate>
+    <ItemTemplate>
+        <li><%# Eval("Name") %> - <%# Eval("Price", "{0:C}") %></li>
+    </ItemTemplate>
+    <FooterTemplate>
+        </ul>
+    </FooterTemplate>
+</asp:Repeater>
+
+
+
+
<Repeater Items="@products" ItemType="Product" Context="Item">
+    <HeaderTemplate>
+        <ul>
+    </HeaderTemplate>
+    <ItemTemplate>
+        <li>@Item.Name - @Item.Price.ToString("C")</li>
+    </ItemTemplate>
+    <FooterTemplate>
+        </ul>
+    </FooterTemplate>
+</Repeater>
+
+
+
+
+

See Also

+
    +
  • DataList — Repeating data with table/flow layout options
    • +
  • DataGrid — Legacy grid control
    • +
  • ListView — Full-featured list with CRUD, paging, and grouping
    • +
  • GridView — Tabular data grid
    • +
  • DataPager — Shared paging for multiple controls
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/AdRotator/index.html b/site/EditorControls/AdRotator/index.html new file mode 100644 index 000000000..d166089a0 --- /dev/null +++ b/site/EditorControls/AdRotator/index.html @@ -0,0 +1,5042 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AdRotator - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

AdRotator

+ +

The AdRotator component is meant to emulate the asp:AdRotator control in markup and is defined in the System.Web.UI.WebControls.AdRotator class

+

Blazor Features Supported

+

XML File-Based Advertisement

+
    +
  • AdvertisementFile - The path to an XML file that contains advertisement information.
    • +
  • Target - The name of the browser window or frame that displays the contents of the Web page linked to when the AdRotator component is clicked.
    • +
  • KeywordFilter - Filter advertisements by keyword.
    • +
  • AlternateTextField - The field name in the data source that provides alternate text for the ad image (default: "AlternateText").
    • +
  • ImageUrlField - The field name in the data source that provides the image URL (default: "ImageUrl").
    • +
  • NavigateUrlField - The field name in the data source that provides the navigation URL (default: "NavigateUrl").
    • +
+

Data Binding

+
    +
  • DataSource - Bind to a collection of Advertisment objects programmatically. When using DataSource, you can provide a List<Advertisment> or other collection types.
    • +
  • DataMember - Specifies the data table within a DataSet to bind to when using complex data sources.
    • +
  • OnDataBound - Event fired after the data has been bound to the control.
    • +
+

Events

+
    +
  • OnAdCreated - Event fired when an advertisement is created, allowing you to modify ad properties before rendering.
    • +
+

Styling

+
    +
  • Standard Web Forms styling properties: BackColor, ForeColor, BorderColor, BorderStyle, BorderWidth, CssClass, Font, Height, Width.
    • +
+

Usage Examples

+

Using XML Advertisement File

+
<AdRotator AdvertisementFile="Ads.xml" Target="_blank" />
+
+

XML File Format (Ads.xml): +

<Advertisements>
+  <Ad>
+    <ImageUrl>~/images/ad1.jpg</ImageUrl>
+    <NavigateUrl>http://www.example1.com</NavigateUrl>
+    <AlternateText>Visit Example 1</AlternateText>
+    <Width>468</Width>
+    <Height>60</Height>
+    <Keyword>technology</Keyword>
+    <Impressions>80</Impressions>
+  </Ad>
+  <Ad>
+    <ImageUrl>~/images/ad2.jpg</ImageUrl>
+    <NavigateUrl>http://www.example2.com</NavigateUrl>
+    <AlternateText>Visit Example 2</AlternateText>
+    <Width>468</Width>
+    <Height>60</Height>
+    <Keyword>sports</Keyword>
+    <Impressions>20</Impressions>
+  </Ad>
+</Advertisements>
+

+

Using DataSource with List of Advertisements

+
@code {
+    private List<Advertisment> _ads = new()
+    {
+        new Advertisment
+        {
+            ImageUrl = "/images/tech-ad.jpg",
+            NavigateUrl = "http://www.techsite.com",
+            AlternateText = "Visit Tech Site",
+            Width = "468",
+            Height = "60",
+            Keyword = "technology"
+        },
+        new Advertisment
+        {
+            ImageUrl = "/images/sports-ad.jpg",
+            NavigateUrl = "http://www.sportssite.com",
+            AlternateText = "Visit Sports Site",
+            Width = "468",
+            Height = "60",
+            Keyword = "sports"
+        }
+    };
+}
+
+<AdRotator DataSource="@_ads" Target="_blank" />
+
+

Using KeywordFilter

+

Filter advertisements by keyword:

+
<AdRotator AdvertisementFile="Ads.xml" KeywordFilter="technology" Target="_blank" />
+
+

Or with DataSource:

+
<AdRotator DataSource="@_ads" KeywordFilter="technology" Target="_blank" />
+
+

Handling OnAdCreated Event

+

Modify advertisement properties before rendering:

+
<AdRotator AdvertisementFile="Ads.xml" OnAdCreated="HandleAdCreated" />
+
+@code {
+    private void HandleAdCreated(AdCreatedEventArgs e)
+    {
+        // Modify the ad before it's rendered
+        e.AlternateText = $"Special Offer: {e.AlternateText}";
+
+        // Access all ad properties
+        var imageUrl = e.ImageUrl;
+        var navigateUrl = e.NavigateUrl;
+
+        // Access additional properties via AdProperties dictionary
+        var keyword = e.AdProperties["Keyword"];
+    }
+}
+
+

Handling OnDataBound Event

+

Execute code after data binding:

+
<AdRotator DataSource="@_ads" OnDataBound="HandleDataBound" />
+
+@code {
+    private void HandleDataBound(EventArgs e)
+    {
+        // Perform actions after data is bound
+        Console.WriteLine("AdRotator data bound successfully");
+    }
+}
+
+

Using with Styling Properties

+
<AdRotator 
+    AdvertisementFile="Ads.xml" 
+    Target="_blank"
+    CssClass="ad-banner"
+    BorderWidth="1px"
+    BorderColor="#cccccc"
+    BorderStyle="Solid" />
+
+

Notes

+
    +
  • When both DataSource and AdvertisementFile are specified, DataSource takes priority.
    • +
  • The AdRotator randomly selects an advertisement from the available pool each time it renders.
    • +
  • The Impressions field in the XML affects the probability of an ad being shown (ads with higher impression values appear more frequently).
    • +
  • Custom field names can be specified using AlternateTextField, ImageUrlField, and NavigateUrlField properties.
    • +
+

Web Forms Features NOT Supported

+
    +
  • DataSourceID - DataSource controls are not used in Blazor. Use the DataSource property instead to bind data programmatically.
    • +
  • Lifecycle events like OnInit, OnLoad, OnPreRender, OnUnload - These are part of the Web Forms page lifecycle and don't apply to Blazor components.
    • +
  • EnableTheming / SkinID - Blazor uses CSS for theming.
    • +
  • EnableViewState - Blazor doesn't use ViewState.
    • +
+

Syntax Comparison

+
+
+
+
<asp:AdRotator
+    AccessKey="string"
+    AdvertisementFile="uri"
+    AlternateTextField="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    DataMember="string"
+    DataSource="string"
+    DataSourceID="string"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    ImageUrlField="string"
+    KeywordFilter="string"
+    NavigateUrlField="string"
+    OnAdCreated="AdCreated event handler"
+    OnDataBinding="DataBinding event handler"
+    OnDataBound="DataBound event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    Target="string|_blank|_parent|_search|_self|_top"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<AdRotator
+    AdvertisementFile="Ads.xml"
+    KeywordFilter="technology"
+    Target="_blank"
+    OnAdCreated="HandleAdCreated"
+    CssClass="ad-banner"
+    BorderStyle="Solid"
+    BorderWidth="1px" />
+
+@code {
+    private void HandleAdCreated(AdCreatedEventArgs e)
+    {
+        // Modify ad properties before rendering
+        e.AlternateText = $"Special: {e.AlternateText}";
+    }
+}
+
+
+
+
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/BulletedList/index.html b/site/EditorControls/BulletedList/index.html new file mode 100644 index 000000000..7f549bd31 --- /dev/null +++ b/site/EditorControls/BulletedList/index.html @@ -0,0 +1,5512 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BulletedList - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

BulletedList

+

The BulletedList component renders items as a bulleted or numbered list. It supports multiple bullet styles, display modes (text, hyperlink, or clickable link buttons), and both static items and data-bound scenarios.

+

Original Web Forms documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.bulletedlist?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Static items via StaticItems parameter with ListItemCollection
    • +
  • Data binding via Items parameter with DataTextField and DataValueField
    • +
  • Multiple bullet styles: Disc, Circle, Square, Numbered, LowerAlpha, UpperAlpha, LowerRoman, UpperRoman, CustomImage
    • +
  • Display modes: Text (default), HyperLink, LinkButton
    • +
  • FirstBulletNumber for starting ordered lists at a specific number
    • +
  • BulletImageUrl for custom bullet images
    • +
  • Target attribute for hyperlinks (e.g., "_blank")
    • +
  • OnClick event handler for LinkButton mode
    • +
  • Disabled state via Enabled parameter (affects entire control or individual items)
    • +
  • Style attributes (BackColor, ForeColor, Font, BorderStyle, etc.) and CssClass formatting
    • +
+

WebForms Features Not Supported

+
    +
  • DataSourceID - Not supported; bind directly to collections via Items parameter
    • +
+

Syntax Comparison

+
+
+
+
<asp:BulletedList
+    ID="string"
+    runat="server"
+    BulletImageUrl="uri"
+    BulletStyle="NotSet|Numbered|LowerAlpha|UpperAlpha|LowerRoman|UpperRoman|Disc|Circle|Square|CustomImage"
+    DataSourceID="string"
+    DataTextField="string"
+    DataValueField="string"
+    DisplayMode="Text|HyperLink|LinkButton"
+    Enabled="True|False"
+    FirstBulletNumber="integer"
+    Target="string|_blank|_parent|_search|_self|_top"
+    Visible="True|False"
+    OnClick="Click event handler">
+
+    <asp:ListItem Value="value1" Text="Item 1" />
+    <asp:ListItem Value="http://example.com" Text="Link" />
+
+</asp:BulletedList>
+
+
+
+
<BulletedList TItem="object" StaticItems="items" />
+
+@code {
+    private ListItemCollection items = new()
+    {
+        new ListItem("First item", "1"),
+        new ListItem("Second item", "2"),
+        new ListItem("Third item", "3")
+    };
+}
+
+
+
+
+

Data Binding

+
<BulletedList TItem="Product"
+              Items="products"
+              DataTextField="Name"
+              DataValueField="Url"
+              DisplayMode="BulletedListDisplayMode.HyperLink" />
+
+@code {
+    private List<Product> products = new()
+    {
+        new Product { Name = "Laptop", Url = "/products/laptop" },
+        new Product { Name = "Phone", Url = "/products/phone" },
+        new Product { Name = "Tablet", Url = "/products/tablet" }
+    };
+
+    public class Product
+    {
+        public string Name { get; set; }
+        public string Url { get; set; }
+    }
+}
+
+ +
<BulletedList TItem="object"
+              StaticItems="links"
+              DisplayMode="BulletedListDisplayMode.HyperLink"
+              Target="_blank" />
+
+@code {
+    private ListItemCollection links = new()
+    {
+        new ListItem("Microsoft", "https://microsoft.com"),
+        new ListItem("GitHub", "https://github.com"),
+        new ListItem("Azure", "https://azure.com")
+    };
+}
+
+

LinkButton Mode with Click Handler

+
<BulletedList TItem="object"
+              StaticItems="items"
+              DisplayMode="BulletedListDisplayMode.LinkButton"
+              OnClick="HandleItemClick" />
+
+<p>@message</p>
+
+@code {
+    private string message = "";
+
+    private ListItemCollection items = new()
+    {
+        new ListItem("Option A", "a"),
+        new ListItem("Option B", "b"),
+        new ListItem("Option C", "c")
+    };
+
+    private void HandleItemClick(BulletedListEventArgs e)
+    {
+        message = $"You clicked item at index {e.Index}";
+    }
+}
+
+

Numbered List Starting at 5

+
<BulletedList TItem="object"
+              StaticItems="items"
+              BulletStyle="BulletStyle.Numbered"
+              FirstBulletNumber="5" />
+
+

Custom Bullet Image

+
<BulletedList TItem="object"
+              StaticItems="items"
+              BulletStyle="BulletStyle.CustomImage"
+              BulletImageUrl="/images/custom-bullet.png" />
+
+

With Styling

+
<BulletedList TItem="object"
+              StaticItems="items"
+              CssClass="my-list"
+              BackColor="WebColor.LightGray"
+              ForeColor="WebColor.DarkBlue"
+              Width="Unit.Pixel(300)" />
+
+

Bullet Styles

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BulletStyleList TypeCSS/HTML
NotSetUnorderedBrowser default
DiscUnorderedFilled circle (●)
CircleUnorderedEmpty circle (○)
SquareUnorderedFilled square (■)
NumberedOrdered1, 2, 3...
LowerAlphaOrdereda, b, c...
UpperAlphaOrderedA, B, C...
LowerRomanOrderedi, ii, iii...
UpperRomanOrderedI, II, III...
CustomImageUnorderedCustom image via BulletImageUrl
+

Display Modes

+ + + + + + + + + + + + + + + + + + + + + + + + + +
DisplayModeDescriptionRendered As
TextPlain text items (default)<span>
HyperLinkNavigable links using Value as URL<a href="...">
LinkButtonClickable items that fire OnClick event<a href="javascript:void(0)">
+

HTML Output

+

Unordered List (Disc Style)

+
<ul id="myList" style="list-style-type: disc;">
+    <li><span>First item</span></li>
+    <li><span>Second item</span></li>
+</ul>
+
+

Ordered List (Numbered)

+
<ol id="myList" type="1" start="1" style="list-style-type: decimal;">
+    <li><span>First item</span></li>
+    <li><span>Second item</span></li>
+</ol>
+
+ +
<ul id="myList">
+    <li><a href="https://example.com" target="_blank">Link Text</a></li>
+    <li><a href="https://other.com" target="_blank">Another Link</a></li>
+</ul>
+
+

LinkButton Mode

+
<ul id="myList">
+    <li><a href="javascript:void(0)">Clickable Item 1</a></li>
+    <li><a href="javascript:void(0)">Clickable Item 2</a></li>
+</ul>
+
+

Key Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
StaticItemsListItemCollectionemptyStatic list items
ItemsIEnumerable<TItem>nullData-bound items
DataTextFieldstringnullProperty for display text
DataValueFieldstringnullProperty for value (used as URL in HyperLink mode)
BulletStyleBulletStyleNotSetStyle of bullets or numbers
BulletImageUrlstringnullURL of custom bullet image
DisplayModeBulletedListDisplayModeTextHow items are rendered
FirstBulletNumberint1Starting number for ordered lists
TargetstringnullTarget window for hyperlinks
OnClickEventCallback<BulletedListEventArgs>-Click handler for LinkButton mode
ClickEventCallback<BulletedListEventArgs>-Web Forms event alias for OnClick
SelectedIndexint-1Migration stub — accepted for markup compatibility
SelectedValuestringnullMigration stub — accepted for markup compatibility
AutoPostBackboolfalseMigration stub — Blazor events fire immediately
TextstringnullMigration stub — accepted for markup compatibility
+

Key Events

+ + + + + + + + + + + + + + + + + + + + + + + + + +
EventTypeDescription
OnClick / ClickEventCallback<BulletedListEventArgs>Fires when a LinkButton-mode item is clicked
SelectedIndexChangedEventCallback<EventArgs>Migration stub — accepted but not fired by the component
TextChangedEventCallback<EventArgs>Migration stub — accepted but not fired by the component
+

Key Differences from Web Forms

+
    +
  1. Type Parameter: Blazor BulletedList requires a TItem type parameter for data binding
    2. +
  2. Property Names: Use StaticItems for the item collection (not Items), as Items is reserved for data-bound scenarios
    3. +
  3. Event Handling: Uses OnClick (or Click alias) with EventCallback<BulletedListEventArgs> instead of server-side postback
    4. +
  4. Enum References: Use BulletStyle.Numbered and BulletedListDisplayMode.HyperLink syntax
    5. +
  5. No AutoPostBack: AutoPostBack is accepted for migration but Blazor events fire immediately
    6. +
+

BulletedListEventArgs

+

The OnClick event provides a BulletedListEventArgs object with:

+ + + + + + + + + + + + + + + +
PropertyTypeDescription
IndexintZero-based index of the clicked item
+
private void HandleClick(BulletedListEventArgs e)
+{
+    var clickedIndex = e.Index;
+    var clickedItem = items[clickedIndex];
+    Console.WriteLine($"Clicked: {clickedItem.Text}");
+}
+
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove the asp: prefix and runat="server" attribute
    2. +
  2. Add the TItem="object" type parameter (or your specific data type)
    3. +
  3. Remove <asp:ListItem> tags and define items in code-behind as ListItemCollection
    4. +
  4. For LinkButton mode, add an OnClick handler
    5. +
  5. Update enum references to Blazor syntax (e.g., BulletStyle.Numbered)
    6. +
  6. AutoPostBack, SelectedIndex, SelectedValue, and Text are accepted for migration compatibility
    7. +
+

Before (Web Forms):

+
<asp:BulletedList ID="blLinks" 
+                  runat="server"
+                  BulletStyle="Numbered"
+                  DisplayMode="HyperLink"
+                  Target="_blank">
+    <asp:ListItem Value="https://microsoft.com" Text="Microsoft" />
+    <asp:ListItem Value="https://github.com" Text="GitHub" />
+    <asp:ListItem Value="https://azure.com" Text="Azure" />
+</asp:BulletedList>
+
+

After (Blazor):

+
<BulletedList TItem="object"
+              StaticItems="links"
+              BulletStyle="BulletStyle.Numbered"
+              DisplayMode="BulletedListDisplayMode.HyperLink"
+              Target="_blank" />
+
+@code {
+    private ListItemCollection links = new()
+    {
+        new ListItem("Microsoft", "https://microsoft.com"),
+        new ListItem("GitHub", "https://github.com"),
+        new ListItem("Azure", "https://azure.com")
+    };
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Button/index.html b/site/EditorControls/Button/index.html new file mode 100644 index 000000000..25fdd7cd0 --- /dev/null +++ b/site/EditorControls/Button/index.html @@ -0,0 +1,5315 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Button - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Button

+

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.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.button?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • 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)
    • +
  • ValidationGroup - specifies the validation group for which the button triggers validation
    • +
  • 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)
    • +
+

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
    • +
  • AccessKey - Use HTML accesskey attribute directly if needed
    • +
+

Syntax Comparison

+
+
+
+
<asp:Button
+    AccessKey="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CausesValidation="True|False"
+    CommandArgument="string"
+    CommandName="string"
+    CssClass="string"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    OnClick="Click event handler"
+    OnClientClick="string"
+    OnCommand="Command event handler"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    PostBackUrl="uri"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    Text="string"
+    ToolTip="string"
+    UseSubmitBehavior="True|False"
+    ValidationGroup="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<Button Text="Click Me" OnClick="HandleClick" />
+
+@code {
+    void HandleClick()
+    {
+        // Handle the click
+    }
+}
+
+
+
+
+

Blazor Razor Syntax

+

Basic Button with Click Event

+
<Button Text="Click Me" OnClick="HandleClick" />
+
+@code {
+    void HandleClick()
+    {
+        // Handle the click
+    }
+}
+
+

Button with Command

+
<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

+
<Button Text="Alert" OnClientClick="alert('Hello World!')" />
+
+

Styled Button

+
<Button Text="Styled Button"
+        BackColor="WebColor.Blue"
+        ForeColor="WebColor.White"
+        Font_Bold="true"
+        CssClass="my-button-class" />
+
+

Disabled Button

+
<Button Text="Cannot Click" Enabled="false" />
+
+

Button with Validation Control

+
<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>
+
+

ValidationGroup - Selective Validation

+

The ValidationGroup property allows you to create multiple validation groups on a single form. When a button with a ValidationGroup is clicked, only validators with the matching ValidationGroup will be triggered.

+

Important: To use ValidationGroup, you must wrap your form in a ValidationGroupProvider component.

+
@using BlazorWebFormsComponents.Validations
+
+<ValidationGroupProvider>
+    <EditForm Model="@model" OnValidSubmit="HandlePersonalSubmit">
+        @* Personal Information Group *@
+        <InputText @ref="NameInput.Current" @bind-Value="model.Name" />
+        <RequiredFieldValidator ControlToValidate="@NameInput"
+                                Text="Name required"
+                                ValidationGroup="Personal" />
+
+        <InputText @ref="EmailInput.Current" @bind-Value="model.Email" />
+        <RequiredFieldValidator ControlToValidate="@EmailInput"
+                                Text="Email required"
+                                ValidationGroup="Personal" />
+
+        <Button Text="Validate Personal" ValidationGroup="Personal" />
+    </EditForm>
+
+    <EditForm Model="@model" OnValidSubmit="HandleBusinessSubmit">
+        @* Business Information Group *@
+        <InputText @ref="CompanyInput.Current" @bind-Value="model.Company" />
+        <RequiredFieldValidator ControlToValidate="@CompanyInput"
+                                Text="Company required"
+                                ValidationGroup="Business" />
+
+        <Button Text="Validate Business" ValidationGroup="Business" />
+    </EditForm>
+</ValidationGroupProvider>
+
+@code {
+    ForwardRef<InputBase<string>> NameInput = new ForwardRef<InputBase<string>>();
+    ForwardRef<InputBase<string>> EmailInput = new ForwardRef<InputBase<string>>();
+    ForwardRef<InputBase<string>> CompanyInput = new ForwardRef<InputBase<string>>();
+
+    private FormModel model = new FormModel();
+
+    void HandlePersonalSubmit() { /* Personal validation passed */ }
+    void HandleBusinessSubmit() { /* Business validation passed */ }
+}
+
+

How ValidationGroup Works:

+
    +
  1. Same Group - Button with ValidationGroup="Personal" triggers only validators with ValidationGroup="Personal"
    2. +
  2. No Group (empty/null) - Button without a ValidationGroup triggers only validators without a ValidationGroup
    3. +
  3. Multiple Groups - You can have multiple groups on the same page that validate independently
    4. +
  4. CausesValidation - Set CausesValidation="false" to disable validation entirely for a button
    5. +
+

HTML Output

+

Web Forms Input: +

<asp:Button ID="btnSubmit" Text="Submit" CssClass="btn" runat="server" />
+

+

Rendered HTML: +

<button type="submit" class="btn">Submit</button>
+

+

Styled Button Input: +

<Button Text="Styled" BackColor="WebColor.Blue" ForeColor="WebColor.White" />
+

+

Rendered 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. +
  2. Remove runat="server" - Not needed in Blazor
    3. +
  3. Remove ID attribute - Use @ref if you need a reference to the component
    4. +
  4. Update event handler syntax - Change OnClick="btnSubmit_Click" to OnClick="HandleClick"
    5. +
  5. Replace PostBackUrl - Use navigation or component state instead
    6. +
  6. Update OnCommand handlers - The signature changes from (object sender, CommandEventArgs e) to (CommandEventArgs args)
    7. +
+

Before (Web Forms)

+
<asp:Button ID="btnSave" 
+            Text="Save" 
+            OnClick="btnSave_Click" 
+            CssClass="btn btn-primary"
+            runat="server" />
+
+
protected void btnSave_Click(object sender, EventArgs e)
+{
+    // Handle click
+}
+
+

After (Blazor)

+
<Button Text="Save" 
+        OnClick="HandleSave" 
+        CssClass="btn btn-primary" />
+
+@code {
+    void HandleSave()
+    {
+        // Handle click
+    }
+}
+
+

Examples

+

Basic Click Handler

+
<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

+
<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

+
@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

+
<Button Text="Show Alert" OnClientClick="alert('Hello from JavaScript!')" />
+<Button Text="Confirm" OnClientClick="return confirm('Are you sure?')" OnClick="HandleConfirmed" />
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Calendar/index.html b/site/EditorControls/Calendar/index.html new file mode 100644 index 000000000..1b3a2db2f --- /dev/null +++ b/site/EditorControls/Calendar/index.html @@ -0,0 +1,5370 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Calendar - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Calendar

+

The Calendar component provides a Blazor implementation of the ASP.NET Web Forms Calendar control, enabling users to select dates and navigate through months.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.calendar?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • SelectedDate property for single date selection
    • +
  • SelectedDates collection for multi-date selection (read-only)
    • +
  • VisibleDate property to set the displayed month
    • +
  • SelectionMode (None, Day, DayWeek, DayWeekMonth)
    • +
  • Two-way binding with @bind-SelectedDate
    • +
  • Month/year navigation with next/previous buttons
    • +
  • OnSelectionChanged event when a date is selected
    • +
  • OnDayRender event for customizing individual days
    • +
  • OnVisibleMonthChanged event when the month changes
    • +
  • Customizable display options:
    • +
  • ShowTitle - Show/hide title bar
    • +
  • ShowDayHeader - Show/hide day name headers
    • +
  • ShowGridLines - Show/hide grid borders
    • +
  • ShowNextPrevMonth - Show/hide navigation
    • +
  • Day name formatting (DayNameFormat: Full, Short, FirstLetter, FirstTwoLetters, Shortest)
    • +
  • Title formatting (TitleFormat: Month, MonthYear)
    • +
  • Customizable navigation text (NextMonthText, PrevMonthText, SelectWeekText, SelectMonthText)
    • +
  • First day of week configuration (FirstDayOfWeek)
    • +
  • Cell padding and spacing options
    • +
  • TableItemStyle sub-components for rich styling (preferred):
    • +
  • <CalendarDayStyle> - Regular day cells
    • +
  • <CalendarTitleStyle> - Title bar
    • +
  • <CalendarDayHeaderStyle> - Day name headers
    • +
  • <CalendarTodayDayStyle> - Today's date cell
    • +
  • <CalendarSelectedDayStyle> - Selected date cell
    • +
  • <CalendarOtherMonthDayStyle> - Days from adjacent months
    • +
  • <CalendarWeekendDayStyle> - Weekend day cells
    • +
  • <CalendarNextPrevStyle> - Next/previous navigation links
    • +
  • <CalendarSelectorStyle> - Week/month selector column
    • +
  • Each TableItemStyle sub-component supports: CssClass, BackColor, ForeColor, BorderColor, BorderStyle, BorderWidth, Height, Width, HorizontalAlign, VerticalAlign, Wrap, Font-Bold, Font-Italic, Font-Size, Font-Name, etc.
    • +
  • Legacy CSS string properties (deprecated but still functional):
    • +
  • TitleStyleCss, DayHeaderStyleCss, DayStyleCss, TodayDayStyleCss, SelectedDayStyleCss, OtherMonthDayStyleCss, WeekendDayStyleCss, NextPrevStyleCss, SelectorStyleCss
    • +
  • Visible property to show/hide the calendar
    • +
  • CssClass for custom CSS styling
    • +
  • ToolTip for accessibility
    • +
+

Web Forms Features NOT Supported

+
    +
  • DayRender event cannot add custom controls to cells (Blazor limitation)
    • +
  • Caption and CaptionAlign properties not implemented
    • +
  • TodaysDate property not implemented (use DateTime.Today)
    • +
  • UseAccessibleHeader not implemented
    • +
+
+

Style Properties Migration

+

Individual style objects (DayStyle, TitleStyle, etc.) from Web Forms are now supported via TableItemStyle sub-components such as <CalendarDayStyle>, <CalendarTitleStyle>, etc. The older CSS string properties (DayStyleCss, TitleStyleCss, etc.) still work but are deprecated. See the migration example below.

+
+

Syntax Comparison

+
+
+
+
<asp:Calendar
+    CellPadding="2"
+    CellSpacing="0"
+    DayNameFormat="Short|Full|FirstLetter|FirstTwoLetters|Shortest"
+    FirstDayOfWeek="Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Default"
+    ID="string"
+    NextMonthText="string"
+    NextPrevFormat="ShortMonth|FullMonth|CustomText"
+    OnDayRender="DayRenderEventHandler"
+    OnSelectionChanged="EventHandler"
+    OnVisibleMonthChanged="MonthChangedEventHandler"
+    PrevMonthText="string"
+    SelectedDate="DateTime"
+    SelectionMode="None|Day|DayWeek|DayWeekMonth"
+    SelectMonthText="string"
+    SelectWeekText="string"
+    ShowDayHeader="True|False"
+    ShowGridLines="True|False"
+    ShowNextPrevMonth="True|False"
+    ShowTitle="True|False"
+    TitleFormat="Month|MonthYear"
+    VisibleDate="DateTime"
+    runat="server">
+    <DayStyle />
+    <TodayDayStyle />
+    <SelectedDayStyle />
+    <OtherMonthDayStyle />
+    <WeekendDayStyle />
+    <TitleStyle />
+    <NextPrevStyle />
+    <DayHeaderStyle />
+    <SelectorStyle />
+</asp:Calendar>
+
+
+
+
<Calendar
+    CellPadding="2"
+    CellSpacing="0"
+    DayNameFormat="Short|Full|FirstLetter|FirstTwoLetters|Shortest"
+    FirstDayOfWeek="Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday"
+    ID="string"
+    NextMonthText="string"
+    OnDayRender="DayRenderEventHandler"
+    OnSelectionChanged="EventHandler"
+    OnVisibleMonthChanged="MonthChangedEventHandler"
+    PrevMonthText="string"
+    @bind-SelectedDate="dateVariable"
+    SelectionMode="None|Day|DayWeek|DayWeekMonth"
+    SelectMonthText="string"
+    SelectWeekText="string"
+    ShowDayHeader="True|False"
+    ShowGridLines="True|False"
+    ShowNextPrevMonth="True|False"
+    ShowTitle="True|False"
+    TitleFormat="Month|MonthYear"
+    VisibleDate="DateTime"
+    CssClass="string">
+
+    @* TableItemStyle sub-components (preferred) *@
+    <CalendarDayStyle CssClass="string" BackColor="string" ForeColor="string" />
+    <CalendarTitleStyle CssClass="string" BackColor="string" ForeColor="string" Font-Bold="true" />
+    <CalendarDayHeaderStyle CssClass="string" BackColor="string" ForeColor="string" />
+    <CalendarTodayDayStyle CssClass="string" BackColor="string" ForeColor="string" />
+    <CalendarSelectedDayStyle CssClass="string" BackColor="string" ForeColor="string" />
+    <CalendarOtherMonthDayStyle CssClass="string" ForeColor="string" />
+    <CalendarWeekendDayStyle CssClass="string" BackColor="string" />
+    <CalendarNextPrevStyle CssClass="string" ForeColor="string" />
+    <CalendarSelectorStyle CssClass="string" BackColor="string" />
+
+</Calendar>
+
+
+
+
+
+

Deprecated CSS String Properties

+

The following properties still work but are deprecated. Use the TableItemStyle sub-components above instead: +TitleStyleCss, DayStyleCss, TodayDayStyleCss, SelectedDayStyleCss, OtherMonthDayStyleCss, WeekendDayStyleCss, DayHeaderStyleCss, NextPrevStyleCss, SelectorStyleCss

+
+

Usage Examples

+

Basic Calendar

+
@page "/calendar-demo"
+
+<h3>Select a Date</h3>
+<Calendar @bind-SelectedDate="selectedDate" />
+<p>You selected: @selectedDate.ToShortDateString()</p>
+
+@code {
+    private DateTime selectedDate = DateTime.Today;
+}
+
+

Calendar with Week Selection

+
<Calendar SelectionMode="DayWeek" 
+          @bind-SelectedDate="weekStart"
+          OnSelectionChanged="HandleSelection" />
+
+@code {
+    private DateTime weekStart = DateTime.Today;
+
+    private void HandleSelection()
+    {
+        // User selected a week starting at weekStart
+    }
+}
+
+

Calendar with Month Selection

+
<Calendar SelectionMode="DayWeekMonth" 
+          @bind-SelectedDate="monthStart" />
+
+@code {
+    private DateTime monthStart = DateTime.Today;
+}
+
+

Customized Calendar

+
<Calendar ShowGridLines="true"
+          DayNameFormat="Full"
+          TitleFormat="MonthYear"
+          FirstDayOfWeek="DayOfWeek.Monday"
+          NextMonthText="Next →"
+          PrevMonthText="← Prev"
+          @bind-SelectedDate="selectedDate" />
+
+

Styled Calendar (using TableItemStyle sub-components)

+
<Calendar @bind-SelectedDate="selectedDate">
+    <CalendarTitleStyle BackColor="#007bff" ForeColor="White" Font-Bold="true" />
+    <CalendarSelectedDayStyle BackColor="#28a745" ForeColor="White" />
+    <CalendarTodayDayStyle BackColor="#ffc107" Font-Bold="true" />
+    <CalendarWeekendDayStyle BackColor="#f8f9fa" />
+    <CalendarOtherMonthDayStyle ForeColor="#ccc" />
+    <CalendarDayHeaderStyle BackColor="#e9ecef" Font-Bold="true" />
+    <CalendarNextPrevStyle ForeColor="White" />
+</Calendar>
+
+

Styled Calendar (legacy CSS string properties — deprecated)

+
<Calendar CssClass="my-calendar"
+          TitleStyleCss="calendar-title"
+          SelectedDayStyleCss="selected-date"
+          TodayDayStyleCss="today-date"
+          WeekendDayStyleCss="weekend-date"
+          @bind-SelectedDate="selectedDate" />
+
+<style>
+.my-calendar {
+    border: 1px solid #ccc;
+}
+.calendar-title {
+    background-color: #007bff;
+    color: white;
+    font-weight: bold;
+}
+.selected-date {
+    background-color: #28a745;
+    color: white;
+}
+.today-date {
+    background-color: #ffc107;
+    font-weight: bold;
+}
+.weekend-date {
+    background-color: #f8f9fa;
+}
+</style>
+
+

Calendar with Event Handlers

+
<Calendar @bind-SelectedDate="selectedDate"
+          OnSelectionChanged="HandleSelectionChanged"
+          OnVisibleMonthChanged="HandleMonthChanged"
+          OnDayRender="HandleDayRender" />
+
+<p>Selection count: @selectionCount</p>
+<p>Current month: @currentMonth.ToString("MMMM yyyy")</p>
+
+@code {
+    private DateTime selectedDate = DateTime.Today;
+    private int selectionCount = 0;
+    private DateTime currentMonth = DateTime.Today;
+
+    private void HandleSelectionChanged()
+    {
+        selectionCount++;
+    }
+
+    private void HandleMonthChanged(CalendarMonthChangedArgs args)
+    {
+        currentMonth = args.CurrentMonth;
+    }
+
+    private void HandleDayRender(CalendarDayRenderArgs args)
+    {
+        // Disable Sundays
+        if (args.Date.DayOfWeek == DayOfWeek.Sunday)
+        {
+            args.IsSelectable = false;
+        }
+
+        // Disable past dates
+        if (args.Date < DateTime.Today)
+        {
+            args.IsSelectable = false;
+        }
+    }
+}
+
+

Display Specific Month

+
<Calendar VisibleDate="specificMonth"
+          @bind-SelectedDate="selectedDate" />
+
+@code {
+    private DateTime specificMonth = new DateTime(2024, 12, 1);
+    private DateTime selectedDate = DateTime.Today;
+}
+
+

Read-Only Calendar (No Selection)

+
<Calendar SelectionMode="None" 
+          VisibleDate="@DateTime.Today" />
+
+

Migration Notes

+

From Web Forms to Blazor

+

Web Forms: +

<asp:Calendar ID="Calendar1" 
+              runat="server" 
+              OnSelectionChanged="Calendar1_SelectionChanged">
+    <SelectedDayStyle BackColor="Blue" ForeColor="White" />
+</asp:Calendar>
+

+
protected void Calendar1_SelectionChanged(object sender, EventArgs e)
+{
+    DateTime selected = Calendar1.SelectedDate;
+}
+
+

Blazor: +

<Calendar @bind-SelectedDate="selectedDate"
+          OnSelectionChanged="HandleSelectionChanged">
+    <CalendarSelectedDayStyle BackColor="Blue" ForeColor="White" />
+</Calendar>
+

+
@code {
+    private DateTime selectedDate = DateTime.Today;
+
+    private void HandleSelectionChanged()
+    {
+        // Date is available in selectedDate variable
+    }
+}
+
+

Migrating from CSS String Properties to TableItemStyle

+

If you previously used the CSS string properties, migrate to the new sub-components:

+

Before (deprecated): +

<Calendar TitleStyleCss="calendar-title"
+          SelectedDayStyleCss="selected-date"
+          TodayDayStyleCss="today-date"
+          WeekendDayStyleCss="weekend-date"
+          DayHeaderStyleCss="header-style"
+          @bind-SelectedDate="selectedDate" />
+

+

After (preferred): +

<Calendar @bind-SelectedDate="selectedDate">
+    <CalendarTitleStyle CssClass="calendar-title" />
+    <CalendarSelectedDayStyle CssClass="selected-date" />
+    <CalendarTodayDayStyle CssClass="today-date" />
+    <CalendarWeekendDayStyle CssClass="weekend-date" />
+    <CalendarDayHeaderStyle CssClass="header-style" />
+</Calendar>
+

+
+

Best Practice

+

The TableItemStyle sub-components also support inline style properties like BackColor, ForeColor, and Font-Bold — matching the Web Forms <DayStyle>, <TitleStyle>, etc. child elements. This makes migration from Web Forms markup even more direct.

+
+

Key Differences

+
    +
  1. Style Properties: Use TableItemStyle sub-components (<CalendarDayStyle>, <CalendarTitleStyle>, etc.) for a direct match to Web Forms style child elements, or use CssClass for CSS-based styling. Legacy CSS string properties (DayStyleCss, etc.) are deprecated.
    2. +
  2. DayNameFormat / TitleFormat: Use enum values directly — DayNameFormat="Full", DayNameFormat="Short", DayNameFormat="FirstLetter", DayNameFormat="FirstTwoLetters", DayNameFormat="Shortest" for day names; TitleFormat="Month" or TitleFormat="MonthYear" for the title.
    3. +
  3. Event Handlers: Use EventCallback pattern instead of event delegates
    4. +
  4. Data Binding: Use @bind-SelectedDate for two-way binding
    5. +
  5. Day Rendering: The OnDayRender event provides day information but cannot inject custom HTML into cells
    6. +
+

Common Scenarios

+

Date Range Picker

+
<h4>Start Date</h4>
+<Calendar @bind-SelectedDate="startDate" />
+
+<h4>End Date</h4>
+<Calendar @bind-SelectedDate="endDate" OnDayRender="HandleEndDateDayRender" />
+
+@code {
+    private DateTime startDate = DateTime.Today;
+    private DateTime endDate = DateTime.Today.AddDays(7);
+
+    private void HandleEndDateDayRender(CalendarDayRenderArgs args)
+    {
+        // Disable dates before start date
+        if (args.Date < startDate)
+        {
+            args.IsSelectable = false;
+        }
+    }
+}
+
+

Holiday Calendar

+
<Calendar @bind-SelectedDate="selectedDate"
+          OnDayRender="HandleHolidayRender"
+          WeekendDayStyleCss="weekend"
+          OtherMonthDayStyleCss="other-month" />
+
+@code {
+    private DateTime selectedDate = DateTime.Today;
+    private List<DateTime> holidays = new List<DateTime>
+    {
+        new DateTime(2024, 1, 1),  // New Year
+        new DateTime(2024, 7, 4),  // Independence Day
+        new DateTime(2024, 12, 25) // Christmas
+    };
+
+    private void HandleHolidayRender(CalendarDayRenderArgs args)
+    {
+        if (holidays.Contains(args.Date))
+        {
+            args.IsSelectable = false;
+        }
+    }
+}
+
+

See Also

+
    +
  • TextBox - For alternative date input using TextBoxMode.Date
    • +
  • Button - For submitting forms with selected dates
    • +
  • Panel - For grouping calendar with related controls
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/CheckBox/index.html b/site/EditorControls/CheckBox/index.html new file mode 100644 index 000000000..4ac1adf11 --- /dev/null +++ b/site/EditorControls/CheckBox/index.html @@ -0,0 +1,5051 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CheckBox - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

CheckBox

+

The CheckBox component provides a Blazor implementation of the ASP.NET Web Forms CheckBox control, enabling boolean input with an optional text label.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.checkbox?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • Checked property for boolean state
    • +
  • Text property for label display
    • +
  • TextAlign property (Left or Right) for label positioning
    • +
  • Two-way binding with @bind-Checked
    • +
  • OnCheckedChanged event handler
    • +
  • Enabled property to disable the checkbox
    • +
  • Style attributes (BackColor, ForeColor, CssClass, etc.)
    • +
  • Visible property to show/hide the checkbox
    • +
+

Web Forms Features NOT Supported

+
    +
  • AutoPostBack is not supported in Blazor. Use the OnCheckedChanged event instead to react to state changes.
    • +
  • InputAttributes property is not implemented
    • +
  • LabelAttributes property is not implemented
    • +
+

Syntax Comparison

+
+
+
+
<asp:CheckBox
+    AccessKey="string"
+    AutoPostBack="True|False"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    Checked="True|False"
+    CssClass="string"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    OnCheckedChanged="CheckedChanged event handler"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    Text="string"
+    TextAlign="Left|Right"
+    ToolTip="string"
+    ValidationGroup="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<CheckBox Text="I agree to the terms and conditions" />
+
+
+
+
+

Blazor Syntax

+

Basic CheckBox

+
<CheckBox Text="I agree to the terms and conditions" />
+
+

Pre-checked CheckBox

+
<CheckBox Text="Remember me" Checked="true" />
+
+

Two-way Binding

+
<CheckBox Text="Subscribe to newsletter" @bind-Checked="isSubscribed" />
+
+@code {
+    private bool isSubscribed = false;
+}
+
+

Text Alignment

+

By default, the label appears to the right of the checkbox. Use TextAlign to position it on the left:

+
<CheckBox Text="Label on right (default)" />
+<CheckBox Text="Label on left" TextAlign="TextAlign.Left" />
+
+

Event Handling

+
<CheckBox Text="Notify me" OnCheckedChanged="HandleChange" />
+
+@code {
+    private void HandleChange(ChangeEventArgs e)
+    {
+        bool isChecked = (bool)e.Value;
+        // Handle the change
+    }
+}
+
+

Disabled CheckBox

+
<CheckBox Text="This option is disabled" Enabled="false" Checked="true" />
+
+

Styled CheckBox

+
@using static BlazorWebFormsComponents.WebColor
+
+<CheckBox Text="Custom styled" 
+          CssClass="my-checkbox" 
+          BackColor="LightBlue" 
+          ForeColor="Navy" />
+
+

CheckBox without Text

+

When no Text is provided, the checkbox renders without a <span> wrapper or <label>:

+
<CheckBox @bind-Checked="option1" />
+<CheckBox @bind-Checked="option2" />
+<CheckBox @bind-Checked="option3" />
+
+

HTML Output

+

The CheckBox component renders different HTML depending on whether text is provided:

+

With Text (TextAlign=Right, default): +

<span class="custom-class" style="...">
+    <input id="guid" type="checkbox" />
+    <label for="guid">Label text</label>
+</span>
+

+

With Text (TextAlign=Left): +

<span class="custom-class" style="...">
+    <label for="guid">Label text</label>
+    <input id="guid" type="checkbox" />
+</span>
+

+

Without Text: +

<input type="checkbox" class="custom-class" style="..." />
+

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove the asp: prefix and runat="server" attribute
    2. +
  2. Replace AutoPostBack="true" with the OnCheckedChanged event handler
    3. +
  3. Use @bind-Checked for two-way data binding instead of reading Checked in code-behind
    4. +
  4. The ID property is obsolete in Blazor; use @ref to get a reference to the component instance
    5. +
+

Before (Web Forms):

+
<asp:CheckBox ID="chkAgree" 
+              Text="I agree" 
+              AutoPostBack="true"
+              OnCheckedChanged="CheckBox_Changed" 
+              runat="server" />
+
+

After (Blazor):

+
<CheckBox Text="I agree" 
+          @bind-Checked="agreed"
+          OnCheckedChanged="HandleChange" />
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/CheckBoxList/index.html b/site/EditorControls/CheckBoxList/index.html new file mode 100644 index 000000000..1dc218b81 --- /dev/null +++ b/site/EditorControls/CheckBoxList/index.html @@ -0,0 +1,5331 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CheckBoxList - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

CheckBoxList

+

The CheckBoxList component renders a group of checkboxes that allow users to select multiple items from a list. This component supports both static items and data-bound scenarios.

+

Original Web Forms documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.checkboxlist?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Static items via StaticItems parameter with ListItemCollection
    • +
  • Data binding via Items parameter with DataTextField and DataValueField
    • +
  • Two-way binding with @bind-SelectedValues for multiple selections
    • +
  • Layout options: Table (default), Flow, OrderedList, UnorderedList
    • +
  • Repeat direction: Vertical (default) or Horizontal
    • +
  • TextAlign property (Left or Right) for label positioning
    • +
  • CellPadding and CellSpacing for table layout
    • +
  • OnSelectedIndexChanged event handler
    • +
  • Disabled state via Enabled parameter
    • +
  • Style attributes (BackColor, ForeColor, Font, etc.) and CssClass formatting
    • +
+

WebForms Features Not Supported

+
    +
  • AutoPostBack is not supported in Blazor - use OnSelectedIndexChanged event instead
    • +
  • DataSourceID is not supported - bind directly to collections via Items parameter
    • +
+

Syntax Comparison

+
+
+
+
<asp:CheckBoxList
+    ID="string"
+    runat="server"
+    AutoPostBack="True|False"
+    CellPadding="integer"
+    CellSpacing="integer"
+    CssClass="string"
+    DataSourceID="string"
+    DataTextField="string"
+    DataValueField="string"
+    Enabled="True|False"
+    RepeatColumns="integer"
+    RepeatDirection="Horizontal|Vertical"
+    RepeatLayout="Table|Flow|OrderedList|UnorderedList"
+    TextAlign="Left|Right"
+    Visible="True|False"
+    OnSelectedIndexChanged="SelectedIndexChanged event handler">
+
+    <asp:ListItem Value="value1" Text="Option 1" Selected="True|False" />
+    <asp:ListItem Value="value2" Text="Option 2" />
+
+</asp:CheckBoxList>
+
+
+
+
<CheckBoxList TItem="object" StaticItems="items" @bind-SelectedValues="selectedValues" />
+
+@code {
+    private List<string> selectedValues = new();
+
+    private ListItemCollection items = new()
+    {
+        new ListItem("Option One", "1"),
+        new ListItem("Option Two", "2"),
+        new ListItem("Option Three", "3")
+    };
+}
+
+
+
+
+

Data Binding

+
<CheckBoxList TItem="Category"
+              Items="categories"
+              DataTextField="Name"
+              DataValueField="Id"
+              @bind-SelectedValues="selectedCategoryIds" />
+
+@code {
+    private List<string> selectedCategoryIds = new();
+
+    private List<Category> categories = new()
+    {
+        new Category { Id = "1", Name = "Electronics" },
+        new Category { Id = "2", Name = "Clothing" },
+        new Category { Id = "3", Name = "Books" }
+    };
+
+    public class Category
+    {
+        public string Id { get; set; }
+        public string Name { get; set; }
+    }
+}
+
+

With Event Handler

+
<CheckBoxList TItem="object"
+              StaticItems="items"
+              @bind-SelectedValues="selectedValues"
+              OnSelectedIndexChanged="HandleSelectionChanged" />
+
+@code {
+    private List<string> selectedValues = new();
+
+    private void HandleSelectionChanged(ChangeEventArgs e)
+    {
+        Console.WriteLine($"Selection changed. Total selected: {selectedValues.Count}");
+    }
+}
+
+

Text Alignment

+

By default, the label appears to the right of the checkbox. Use TextAlign to position it on the left:

+
<CheckBoxList TItem="object" StaticItems="items" TextAlign="TextAlign.Left" />
+
+

Layout Options

+

Flow Layout (no table, items in a span)

+
<CheckBoxList TItem="object" 
+              StaticItems="items" 
+              RepeatLayout="RepeatLayout.Flow"
+              RepeatDirection="DataListEnum.Vertical" />
+
+

Unordered List Layout

+
<CheckBoxList TItem="object" 
+              StaticItems="items" 
+              RepeatLayout="RepeatLayout.UnorderedList" />
+
+

Horizontal Direction with Multiple Columns

+
<CheckBoxList TItem="object" 
+              StaticItems="items" 
+              RepeatDirection="DataListEnum.Horizontal"
+              RepeatColumns="3" />
+
+

With Styling

+
<CheckBoxList TItem="object"
+              StaticItems="items"
+              CssClass="checkbox-list"
+              CellPadding="5"
+              CellSpacing="2" />
+
+

HTML Output

+

Table Layout (default, vertical direction)

+
<table class="custom-class">
+    <tr>
+        <td><input id="abc_0" type="checkbox" name="abc$0" value="1" /><label for="abc_0">Option 1</label></td>
+    </tr>
+    <tr>
+        <td><input id="abc_1" type="checkbox" name="abc$1" value="2" checked /><label for="abc_1">Option 2</label></td>
+    </tr>
+</table>
+
+

Flow Layout (vertical direction)

+
<span class="custom-class">
+    <input id="abc_0" type="checkbox" name="abc$0" value="1" /><label for="abc_0">Option 1</label><br />
+    <input id="abc_1" type="checkbox" name="abc$1" value="2" /><label for="abc_1">Option 2</label>
+</span>
+
+

Unordered List Layout

+
<ul class="custom-class">
+    <li><input id="abc_0" type="checkbox" name="abc$0" value="1" /><label for="abc_0">Option 1</label></li>
+    <li><input id="abc_1" type="checkbox" name="abc$1" value="2" /><label for="abc_1">Option 2</label></li>
+</ul>
+
+

Key Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
StaticItemsListItemCollectionemptyStatic list items
ItemsIEnumerable<TItem>nullData-bound items
DataTextFieldstringnullProperty for display text
DataValueFieldstringnullProperty for value
SelectedValuesList<string>emptyAll selected values
RepeatColumnsint0Number of columns (0 = auto)
RepeatDirectionDataListEnumVerticalVertical or Horizontal
RepeatLayoutRepeatLayoutTableTable, Flow, OrderedList, UnorderedList
TextAlignTextAlignRightLabel position (Left or Right)
CellPaddingint-1Padding in table layout
CellSpacingint-1Spacing in table layout
+

Key Differences from Web Forms

+
    +
  1. Type Parameter: Blazor CheckBoxList requires a TItem type parameter for data binding
    2. +
  2. Property Names: Use StaticItems for the item collection (not Items), as Items is reserved for data-bound scenarios
    3. +
  3. Two-way Binding: Use @bind-SelectedValues (returns List<string>) for automatic two-way binding
    4. +
  4. RepeatDirection: Uses DataListEnum.Horizontal / DataListEnum.Vertical instead of enum
    5. +
  5. No AutoPostBack: Blazor's event model doesn't require postback; events fire immediately
    6. +
+

Accessing Selected Items

+
var checkboxList = // reference to CheckBoxList component
+
+// Get all selected values
+List<string> values = checkboxList.SelectedValues;
+
+// Get first selected value
+string firstValue = checkboxList.SelectedValue;
+
+// Get all selected items
+IEnumerable<ListItem> selectedItems = checkboxList.SelectedItems;
+
+// Get first selected item
+ListItem firstItem = checkboxList.SelectedItem;
+
+// Get first selected index
+int index = checkboxList.SelectedIndex;
+
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove the asp: prefix and runat="server" attribute
    2. +
  2. Add the TItem="object" type parameter
    3. +
  3. Replace AutoPostBack="true" with the OnSelectedIndexChanged event handler
    4. +
  4. Use @bind-SelectedValues for two-way data binding
    5. +
  5. Remove <asp:ListItem> tags and define items in code-behind as ListItemCollection
    6. +
+

Before (Web Forms):

+
<asp:CheckBoxList ID="cblCategories" 
+                  runat="server"
+                  RepeatDirection="Vertical"
+                  AutoPostBack="true"
+                  OnSelectedIndexChanged="Categories_Changed">
+    <asp:ListItem Value="1" Text="Electronics" />
+    <asp:ListItem Value="2" Text="Clothing" Selected="True" />
+    <asp:ListItem Value="3" Text="Books" />
+</asp:CheckBoxList>
+
+

After (Blazor):

+
<CheckBoxList TItem="object"
+              StaticItems="categoryItems"
+              @bind-SelectedValues="selectedCategories"
+              OnSelectedIndexChanged="HandleCategoryChange" />
+
+@code {
+    private List<string> selectedCategories = new() { "2" };
+
+    private ListItemCollection categoryItems = new()
+    {
+        new ListItem("Electronics", "1"),
+        new ListItem("Clothing", "2"),
+        new ListItem("Books", "3")
+    };
+
+    private void HandleCategoryChange(ChangeEventArgs e)
+    {
+        // Handle the change
+    }
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Content/index.html b/site/EditorControls/Content/index.html new file mode 100644 index 000000000..f901dbb5b --- /dev/null +++ b/site/EditorControls/Content/index.html @@ -0,0 +1,4960 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Content - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Content

+

The Content component emulates the ASP.NET Web Forms <asp:Content> control. A Content control is used in child pages to provide content that fills a ContentPlaceHolder in a master page. This component bridges Web Forms master page syntax with Blazor's layout system.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.content

+

Features Supported in Blazor

+
    +
  • ChildContent — the content to be rendered in the associated ContentPlaceHolder
    • +
  • ContentPlaceHolderID — identifies which ContentPlaceHolder this content is for
    • +
  • Auto-registration with parent MasterPage component
    • +
  • Works with MasterPage and ContentPlaceHolder components
    • +
+

Web Forms Features NOT Supported

+
    +
  • Master page file path resolution (handled by layout system in Blazor)
    • +
  • Multiple content sections in a single page (use separate MasterPage components instead)
    • +
+

Syntax Comparison

+
+
+
+
<!-- MyPage.aspx -->
+<%@ Page Title="Home" Language="C#" MasterPageFile="~/Site.Master" %>
+
+<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server">
+    <h2>Welcome to my page!</h2>
+    <p>This is the page-specific content.</p>
+</asp:Content>
+
+
+
+
<MasterPage>
+    <ChildContent>
+        <div class="header">
+            <h1>My Website</h1>
+        </div>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>Default content</p>
+        </ContentPlaceHolder>
+
+        <div class="footer">
+            <p>&copy; 2024</p>
+        </div>
+    </ChildContent>
+    <Content ContentPlaceHolderID="MainContent">
+        <h2>Page Title</h2>
+        <p>This content replaces the MainContent placeholder.</p>
+    </Content>
+</MasterPage>
+
+
+
+
+

Content controls are placed as children of a MasterPage component. They automatically register with their parent MasterPage.

+

Multiple Content Sections

+
<MasterPage>
+    <ChildContent>
+        <header>
+            <h1>Site Header</h1>
+            <ContentPlaceHolder ID="PageTitle">
+                <p>Default Title</p>
+            </ContentPlaceHolder>
+        </header>
+
+        <main>
+            <ContentPlaceHolder ID="MainContent">
+                <p>Default main content</p>
+            </ContentPlaceHolder>
+        </main>
+    </ChildContent>
+
+    <Content ContentPlaceHolderID="PageTitle">
+        <h2>My Page Title</h2>
+    </Content>
+
+    <Content ContentPlaceHolderID="MainContent">
+        <p>Page-specific main content goes here.</p>
+    </Content>
+</MasterPage>
+
+

Content with HTML Elements

+
<MasterPage>
+    <ChildContent>
+        <ContentPlaceHolder ID="Body">
+            No content provided
+        </ContentPlaceHolder>
+    </ChildContent>
+
+    <Content ContentPlaceHolderID="Body">
+        <article>
+            <h1>Article Title</h1>
+            <p>Article content here.</p>
+            <button>Read More</button>
+        </article>
+    </Content>
+</MasterPage>
+
+

HTML Output

+

Content does not render directly — its ChildContent is injected into the corresponding ContentPlaceHolder. If no ContentPlaceHolder with a matching ID exists, the content is ignored.

+

Blazor Input: +

<MasterPage>
+    <ChildContent>
+        <ContentPlaceHolder ID="Main">
+            <p>Default</p>
+        </ContentPlaceHolder>
+    </ChildContent>
+    <Content ContentPlaceHolderID="Main">
+        <p>Custom Content</p>
+    </Content>
+</MasterPage>
+

+

Rendered HTML: +

<p>Custom Content</p>
+

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDefaultDescription
ChildContentRenderFragmentnullThe content to be injected into the associated ContentPlaceHolder
ContentPlaceHolderIDstringnullThe ID of the ContentPlaceHolder this content is for
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove asp: prefix and runat="server" — Change <asp:Content> to <Content>
    2. +
  2. Keep ContentPlaceHolderID — The ID attribute is used the same way to match content with placeholders
    3. +
  3. Place within MasterPage — Content controls must be children of a MasterPage component
    4. +
  4. Rename Master page reference — Remove MasterPageFile directive; instead nest Content controls in the MasterPage component
    5. +
+

Before (Web Forms)

+
<!-- Site.Master -->
+<%@ Master Language="C#" %>
+<html>
+<body>
+    <header>
+        <h1>My Site</h1>
+    </header>
+
+    <asp:ContentPlaceHolder ID="MainContent" runat="server">
+        <p>Default content</p>
+    </asp:ContentPlaceHolder>
+</body>
+</html>
+
+
<!-- MyPage.aspx -->
+<%@ Page MasterPageFile="~/Site.Master" %>
+
+<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server">
+    <h2>Welcome!</h2>
+    <p>Page content goes here.</p>
+</asp:Content>
+
+

After (Blazor)

+
<!-- MasterLayout.razor -->
+<MasterPage>
+    <ChildContent>
+        <header>
+            <h1>My Site</h1>
+        </header>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>Default content</p>
+        </ContentPlaceHolder>
+    </ChildContent>
+</MasterPage>
+
+
<!-- MyPage.razor -->
+<MasterPage>
+    <ChildContent>
+        <header>
+            <h1>My Site</h1>
+        </header>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>Default content</p>
+        </ContentPlaceHolder>
+    </ChildContent>
+
+    <Content ContentPlaceHolderID="MainContent">
+        <h2>Welcome!</h2>
+        <p>Page content goes here.</p>
+    </Content>
+</MasterPage>
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/ContentPlaceHolder/index.html b/site/EditorControls/ContentPlaceHolder/index.html new file mode 100644 index 000000000..a6d38482f --- /dev/null +++ b/site/EditorControls/ContentPlaceHolder/index.html @@ -0,0 +1,5030 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ContentPlaceHolder - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ContentPlaceHolder

+

The ContentPlaceHolder component emulates the ASP.NET Web Forms <asp:ContentPlaceHolder> control. A ContentPlaceHolder defines a region in a master page where child pages inject content using Content controls. This component bridges Web Forms master page syntax with Blazor's layout system.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.contentplaceholder

+

Features Supported in Blazor

+
    +
  • ID — identifier to match with Content control's ContentPlaceHolderID
    • +
  • ChildContent — default content to display if no Content control provides a replacement
    • +
  • Auto-registration with parent MasterPage component
    • +
  • Renders content provided by child pages via Content controls, or falls back to default ChildContent
    • +
+

Web Forms Features NOT Supported

+
    +
  • Multiple master pages cascading placeholders (use nested layouts in Blazor instead)
    • +
  • Master page inheritance chains with placeholders
    • +
+

Syntax Comparison

+
+
+
+
<!-- Site.Master -->
+<%@ Master Language="C#" %>
+<html>
+<head>
+    <title><%: Page.Title %></title>
+</head>
+<body>
+    <div class="header">
+        <h1>My Website</h1>
+    </div>
+
+    <asp:ContentPlaceHolder ID="MainContent" runat="server">
+        <p>Default content if no page overrides this placeholder</p>
+    </asp:ContentPlaceHolder>
+
+    <div class="footer">
+        <p>&copy; 2024 My Company</p>
+    </div>
+</body>
+</html>
+
+
+
+
<MasterPage>
+    <ChildContent>
+        <div class="header">
+            <h1>My Website</h1>
+        </div>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>This is the default content for the main area.</p>
+        </ContentPlaceHolder>
+
+        <div class="footer">
+            <p>&copy; 2024 My Company</p>
+        </div>
+    </ChildContent>
+</MasterPage>
+
+
+
+
+

ContentPlaceHolder components are placed within the ChildContent of a MasterPage component. They automatically register with the parent MasterPage.

+

Multiple ContentPlaceHolders

+
<MasterPage>
+    <ChildContent>
+        <header>
+            <ContentPlaceHolder ID="PageTitle">
+                <h1>Default Title</h1>
+            </ContentPlaceHolder>
+        </header>
+
+        <aside>
+            <ContentPlaceHolder ID="Sidebar">
+                <nav>
+                    <ul>
+                        <li><a href="/">Home</a></li>
+                        <li><a href="/about">About</a></li>
+                    </ul>
+                </nav>
+            </ContentPlaceHolder>
+        </aside>
+
+        <main>
+            <ContentPlaceHolder ID="MainContent">
+                <p>Main content goes here</p>
+            </ContentPlaceHolder>
+        </main>
+    </ChildContent>
+</MasterPage>
+
+

Empty ContentPlaceHolder with Content Requirement

+
<MasterPage>
+    <ChildContent>
+        <div class="container">
+            <ContentPlaceHolder ID="Content">
+                <!-- No default content - pages must provide content -->
+            </ContentPlaceHolder>
+        </div>
+    </ChildContent>
+</MasterPage>
+
+

ContentPlaceHolder with Styled Default Content

+
<MasterPage>
+    <ChildContent>
+        <div class="main">
+            <ContentPlaceHolder ID="MainContent">
+                <div class="alert alert-info">
+                    <p>No custom content provided. This is the default message.</p>
+                </div>
+            </ContentPlaceHolder>
+        </div>
+    </ChildContent>
+</MasterPage>
+
+

HTML Output

+

ContentPlaceHolder renders either the content provided by a child page's Content control, or its default ChildContent if no matching Content is found.

+

Blazor Input (with matching Content): +

<MasterPage>
+    <ChildContent>
+        <ContentPlaceHolder ID="Main">
+            <p>Default</p>
+        </ContentPlaceHolder>
+    </ChildContent>
+    <Content ContentPlaceHolderID="Main">
+        <p>Custom Content</p>
+    </Content>
+</MasterPage>
+

+

Rendered HTML: +

<p>Custom Content</p>
+

+

Blazor Input (no matching Content): +

<MasterPage>
+    <ChildContent>
+        <ContentPlaceHolder ID="Main">
+            <p>Default</p>
+        </ContentPlaceHolder>
+    </ChildContent>
+</MasterPage>
+

+

Rendered HTML: +

<p>Default</p>
+

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDefaultDescription
IDstringnullThe unique identifier for this placeholder; used by Content controls to match ContentPlaceHolderID
ChildContentRenderFragmentnullThe default content to render if no Content control provides a replacement
VisiblebooltrueControls whether the placeholder and its content are rendered (inherited from BaseWebFormsComponent)
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove asp: prefix and runat="server" — Change <asp:ContentPlaceHolder> to <ContentPlaceHolder>
    2. +
  2. Keep the ID — The ID attribute is used the same way to match placeholders with Content controls
    3. +
  3. Place within MasterPage — ContentPlaceHolder must be a child of a MasterPage component
    4. +
  4. Default content becomes ChildContent — What was inside the Web Forms tag becomes the ChildContent of the component
    5. +
+

Before (Web Forms)

+
<!-- Site.Master -->
+<%@ Master Language="C#" %>
+<html>
+<body>
+    <div class="sidebar">
+        <asp:ContentPlaceHolder ID="SidebarContent" runat="server">
+            <p>Default sidebar</p>
+        </asp:ContentPlaceHolder>
+    </div>
+
+    <div class="main">
+        <asp:ContentPlaceHolder ID="MainContent" runat="server">
+            <p>Default main area</p>
+        </asp:ContentPlaceHolder>
+    </div>
+</body>
+</html>
+
+<!-- MyPage.aspx -->
+<%@ Page MasterPageFile="~/Site.Master" %>
+
+<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server">
+    <h1>My Page</h1>
+    <p>My content here</p>
+</asp:Content>
+
+

After (Blazor)

+
<!-- MasterLayout.razor -->
+<MasterPage>
+    <ChildContent>
+        <div class="sidebar">
+            <ContentPlaceHolder ID="SidebarContent">
+                <p>Default sidebar</p>
+            </ContentPlaceHolder>
+        </div>
+
+        <div class="main">
+            <ContentPlaceHolder ID="MainContent">
+                <p>Default main area</p>
+            </ContentPlaceHolder>
+        </div>
+    </ChildContent>
+</MasterPage>
+
+<!-- MyPage.razor -->
+<MasterPage>
+    <ChildContent>
+        <div class="sidebar">
+            <ContentPlaceHolder ID="SidebarContent">
+                <p>Default sidebar</p>
+            </ContentPlaceHolder>
+        </div>
+
+        <div class="main">
+            <ContentPlaceHolder ID="MainContent">
+                <p>Default main area</p>
+            </ContentPlaceHolder>
+        </div>
+    </ChildContent>
+
+    <Content ContentPlaceHolderID="MainContent">
+        <h1>My Page</h1>
+        <p>My content here</p>
+    </Content>
+</MasterPage>
+
+

See Also

+
    +
  • Content — Provides content to fill ContentPlaceHolder regions
    • +
  • MasterPage — Container for master page layouts
    • +
  • Migration: Master Pages — Comprehensive master page migration guide
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/DropDownList/index.html b/site/EditorControls/DropDownList/index.html new file mode 100644 index 000000000..2988c5bab --- /dev/null +++ b/site/EditorControls/DropDownList/index.html @@ -0,0 +1,5013 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DropDownList - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

DropDownList

+

The DropDownList component renders an HTML <select> element that allows users to select a single item from a drop-down list. This component supports both static items and data-bound scenarios.

+

Original Web Forms documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.dropdownlist?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Static items via StaticItems parameter with ListItem collection
    • +
  • Data binding via Items parameter with DataTextField and DataValueField
    • +
  • Two-way binding with @bind-SelectedValue
    • +
  • Selected item tracking via SelectedValue and SelectedIndex
    • +
  • OnSelectedIndexChanged event handler
    • +
  • Disabled state via Enabled parameter
    • +
  • Style attributes (BackColor, ForeColor, Font, etc.) and CssClass formatting
    • +
  • Access to SelectedItem property
    • +
+

WebForms Features Not Supported

+
    +
  • AutoPostBack is not supported in Blazor - use OnSelectedIndexChanged event instead
    • +
  • AppendDataBoundItems is not implemented
    • +
  • DataSourceID is not supported - bind directly to collections via Items parameter
    • +
+

Syntax Comparison

+
+
+
+
<asp:DropDownList
+    AccessKey="string"
+    AutoPostBack="True|False"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    DataSourceID="string"
+    DataTextField="string"
+    DataValueField="string"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnSelectedIndexChanged="SelectedIndexChanged event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    SelectedIndex="number"
+    SelectedValue="string"
+    TabIndex="integer"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size">
+
+    <asp:ListItem Value="value1" Text="Display Text 1" Selected="True|False" />
+    <asp:ListItem Value="value2" Text="Display Text 2" />
+
+</asp:DropDownList>
+
+
+
+
<DropDownList TItem="object" StaticItems="items" @bind-SelectedValue="selectedValue" />
+
+@code {
+    private string selectedValue = "";
+
+    private ListItemCollection items = new()
+    {
+        new ListItem("Select...", ""),
+        new ListItem("Option One", "1"),
+        new ListItem("Option Two", "2"),
+        new ListItem("Option Three", "3")
+    };
+}
+
+
+
+
+

Data Binding

+
<DropDownList TItem="Product"
+              Items="products"
+              DataTextField="Name"
+              DataValueField="Id"
+              @bind-SelectedValue="selectedProductId" />
+
+@code {
+    private string selectedProductId = "";
+
+    private List<Product> products = new()
+    {
+        new Product { Id = "1", Name = "Widget" },
+        new Product { Id = "2", Name = "Gadget" },
+        new Product { Id = "3", Name = "Gizmo" }
+    };
+
+    public class Product
+    {
+        public string Id { get; set; }
+        public string Name { get; set; }
+    }
+}
+
+

With Event Handler

+
<DropDownList TItem="object"
+              StaticItems="items"
+              @bind-SelectedValue="selectedValue"
+              OnSelectedIndexChanged="HandleSelectionChanged" />
+
+@code {
+    private string selectedValue = "";
+
+    private void HandleSelectionChanged(ChangeEventArgs e)
+    {
+        var newValue = e.Value?.ToString();
+        Console.WriteLine($"Selection changed to: {newValue}");
+    }
+}
+
+

With Styling

+
<DropDownList TItem="object"
+              StaticItems="items"
+              CssClass="form-select"
+              BackColor="new WebColor(System.Drawing.Color.LightYellow)"
+              Font="new FontInfo { Bold = true }" />
+
+

Key Differences from Web Forms

+
    +
  1. Type Parameter: Blazor DropDownList requires a TItem type parameter for data binding
    2. +
  2. Property Names: Use StaticItems for the item collection (not Items), as Items is reserved for data-bound scenarios
    3. +
  3. Two-way Binding: Use @bind-SelectedValue for automatic two-way binding
    4. +
  4. Events: Use OnSelectedIndexChanged with ChangeEventArgs instead of specialized event args
    5. +
  5. No AutoPostBack: Blazor's event model doesn't require postback; events fire immediately
    6. +
+

ListItem and ListItemCollection

+

The ListItem class represents individual items in the dropdown:

+
public class ListItem
+{
+    public string Text { get; set; }
+    public string Value { get; set; }
+    public bool Selected { get; set; }
+    public bool Enabled { get; set; } = true;
+
+    public ListItem(string text)
+    public ListItem(string text, string value)
+    public ListItem(string text, string value, bool selected)
+}
+
+

The ListItemCollection class provides helper methods:

+
public class ListItemCollection : List<ListItem>
+{
+    public ListItem FindByValue(string value)
+    public ListItem FindByText(string text)
+}
+
+

Common Patterns

+

Pre-select an Item

+
<DropDownList TItem="object" StaticItems="items" SelectedValue="2" />
+
+

Disabled DropDownList

+
<DropDownList TItem="object" StaticItems="items" Enabled="false" />
+
+

Get Selected Item Details

+
var dropdown = // reference to DropDownList component
+var selectedItem = dropdown.SelectedItem;
+var text = selectedItem?.Text;
+var value = selectedItem?.Value;
+
+

Migration Tips

+

When migrating from Web Forms:

+
    +
  1. Replace <asp:DropDownList> with <DropDownList TItem="object">
    2. +
  2. Rename any Items parameter to StaticItems
    3. +
  3. Replace AutoPostBack="true" with OnSelectedIndexChanged event handler
    4. +
  4. Use @bind-SelectedValue instead of manually managing SelectedValue
    5. +
  5. Remove runat="server" attribute
    6. +
  6. Remove <asp:ListItem> tags and define items in code-behind as ListItemCollection
    7. +
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/FileUpload/index.html b/site/EditorControls/FileUpload/index.html new file mode 100644 index 000000000..ed2b0905d --- /dev/null +++ b/site/EditorControls/FileUpload/index.html @@ -0,0 +1,5173 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FileUpload - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

FileUpload

+

The FileUpload component provides file upload functionality that emulates the ASP.NET Web Forms FileUpload control. It renders an HTML file input element and exposes properties and methods familiar to Web Forms developers, such as HasFile, FileName, PostedFile, and SaveAs.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.fileupload?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • HasFile — indicates whether a file has been selected
    • +
  • FileName — the name of the selected file
    • +
  • FileBytes — the file content as a byte array (synchronous)
    • +
  • FileContent — a Stream pointing to the uploaded file
    • +
  • PostedFile — a PostedFileWrapper providing ContentLength, ContentType, FileName, InputStream, and SaveAs (compatible with Web Forms HttpPostedFile patterns)
    • +
  • AllowMultiple — enables multi-file selection (default: false)
    • +
  • Accept — restricts file types via the HTML accept attribute (e.g., ".jpg,.png" or "image/*")
    • +
  • MaxFileSize — maximum file size in bytes (default: 512000 / ~500 KiB)
    • +
  • ToolTip — tooltip text displayed on hover
    • +
  • OnFileSelected — event raised when a file is selected
    • +
  • SaveAs(filename) — saves the uploaded file to a specified server path
    • +
  • GetFileBytesAsync() — async method to get file content as a byte array
    • +
  • GetMultipleFiles() — returns all selected files when AllowMultiple is enabled
    • +
  • SaveAllFiles(directory) — saves all uploaded files to a directory with sanitized filenames
    • +
  • Enabled — enables or disables the file input
    • +
  • Visible — controls visibility
    • +
  • All base style properties (CssClass, Style, BackColor, ForeColor, BorderColor, BorderStyle, BorderWidth, Width, Height, Font)
    • +
+

Blazor Notes

+
    +
  • The control uses Blazor's InputFile component internally, which renders as a standard HTML <input type="file"> element
    • +
  • File processing must be handled through component properties or methods
    • +
  • The OnFileSelected event fires when files are selected
    • +
  • Maximum file size should be configured based on your server's capabilities
    • +
  • For Blazor WebAssembly, file data is read in the browser before being sent to the server
    • +
+

Web Forms Features NOT Supported

+
    +
  • PostedFile.SaveAs with HttpContext — Blazor's SaveAs works directly with IBrowserFile streams; there is no HttpContext-based file handling
    • +
  • Server.MapPath — Use absolute paths or IWebHostEnvironment.WebRootPath in Blazor
    • +
  • Request.Files collection — Use the component's GetMultipleFiles() method instead
    • +
  • Lifecycle events (OnDataBinding, OnInit, etc.) — Use Blazor lifecycle methods instead
    • +
  • Direct postback behavior - use event handlers instead
    • +
  • Automatic form submission - implement form handling in Blazor
    • +
  • Server-side file system access in WebAssembly - must send to API endpoint
    • +
+

Syntax Comparison

+
+
+
+
<asp:FileUpload
+<asp:FileUpload
+    AccessKey="string"
+    AllowMultiple="True|False"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    Enabled="True|False"
+    Height="size"
+    ID="string"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+    runat="server" />
+
+
+
+
<FileUpload OnFileSelected="HandleFileSelected" />
+
+@code {
+    void HandleFileSelected(InputFileChangeEventArgs args)
+    {
+        // File has been selected
+    }
+}
+
+
+
+
+

File Upload with Type Restriction

+
<FileUpload Accept=".jpg,.png,.gif"
+            OnFileSelected="HandleImageSelected" />
+
+

Multiple File Upload

+
<FileUpload AllowMultiple="true"
+            OnFileSelected="HandleFilesSelected" />
+
+

File Upload with Increased Size Limit

+
<FileUpload MaxFileSize="10485760"
+            OnFileSelected="HandleLargeFile" />
+
+@code {
+    async Task HandleLargeFile(InputFileChangeEventArgs args)
+    {
+        // MaxFileSize is set to 10 MB
+    }
+}
+
+

Saving an Uploaded File

+
@inject IWebHostEnvironment Environment
+
+<FileUpload @ref="uploader" OnFileSelected="HandleFile" />
+<Button Text="Upload" OnClick="SaveFile" />
+
+@code {
+    private FileUpload uploader;
+
+    void HandleFile(InputFileChangeEventArgs args)
+    {
+        // File selected, ready to save
+    }
+
+    async Task SaveFile()
+    {
+        if (uploader.HasFile)
+        {
+            var path = Path.Combine(Environment.WebRootPath, "uploads", uploader.FileName);
+            await uploader.SaveAs(path);
+        }
+    }
+}
+
+

Using PostedFile (Web Forms Pattern)

+
<FileUpload @ref="uploader" OnFileSelected="HandleFile" />
+
+@code {
+    private FileUpload uploader;
+
+    void HandleFile(InputFileChangeEventArgs args)
+    {
+        if (uploader.HasFile)
+        {
+            var postedFile = uploader.PostedFile;
+            var fileName = postedFile.FileName;
+            var contentType = postedFile.ContentType;
+            var size = postedFile.ContentLength;
+        }
+    }
+}
+
+

Multiple File Save

+
<FileUpload @ref="uploader"
+            AllowMultiple="true"
+            OnFileSelected="HandleFiles" />
+<Button Text="Save All" OnClick="SaveAllFiles" />
+
+@code {
+    private FileUpload uploader;
+
+    void HandleFiles(InputFileChangeEventArgs args) { }
+
+    async Task SaveAllFiles()
+    {
+        if (uploader.HasFile)
+        {
+            var savedPaths = await uploader.SaveAllFiles("C:\\uploads");
+            // savedPaths contains the full path of each saved file
+        }
+    }
+}
+
+

HTML Output

+

Blazor Input: +

<FileUpload CssClass="file-input" Accept=".pdf,.doc" AllowMultiple="true" />
+

+

Rendered HTML: +

<input type="file" multiple="true" accept=".pdf,.doc" class="file-input" />
+

+

PostedFileWrapper Reference

+

The PostedFile property returns a PostedFileWrapper object that mirrors the Web Forms HttpPostedFile API:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property/MethodTypeDescription
ContentLengthlongSize of the uploaded file in bytes
ContentTypestringMIME content type of the file
FileNamestringName of the uploaded file
InputStreamStreamStream pointing to the file content
SaveAs(filename)TaskSaves the file to the specified path
+

Security Considerations

+
    +
  • Always validate file types on the server side, not just through the Accept attribute
    • +
  • Set appropriate MaxFileSize limits to prevent denial-of-service attacks
    • +
  • Sanitize file names before saving to prevent directory traversal attacks
    • +
  • Scan uploaded files for malware before processing
    • +
  • Store uploaded files outside of the web root when possible
    • +
  • Implement authentication and authorization for file upload endpoints
    • +
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove asp: prefix — Change <asp:FileUpload> to <FileUpload>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Remove ID attribute — Use @ref to get a component reference
    4. +
  4. Replace PostBack button pattern — In Web Forms, a separate Button triggered the upload via PostBack. In Blazor, use the OnFileSelected event or a Button with @ref to call SaveAs
    5. +
  5. Replace Server.MapPath — Use IWebHostEnvironment.WebRootPath or ContentRootPath for server paths
    6. +
  6. Use async methods — Prefer GetFileBytesAsync() over FileBytes for better performance
    7. +
+

Before (Web Forms)

+
<asp:FileUpload ID="fileUpload1" runat="server" />
+<asp:Button ID="btnUpload" Text="Upload" OnClick="btnUpload_Click" runat="server" />
+<asp:Label ID="lblStatus" runat="server" />
+
+
protected void btnUpload_Click(object sender, EventArgs e)
+{
+    if (fileUpload1.HasFile)
+    {
+        string fileName = fileUpload1.FileName;
+        string savePath = Server.MapPath("~/uploads/") + fileName;
+        fileUpload1.SaveAs(savePath);
+        lblStatus.Text = "File uploaded: " + fileName;
+    }
+}
+
+

After (Blazor)

+
@inject IWebHostEnvironment Environment
+
+<FileUpload @ref="fileUpload" OnFileSelected="HandleFile" />
+<Button Text="Upload" OnClick="Upload" />
+<Label Text="@statusMessage" />
+
+@code {
+    private FileUpload fileUpload;
+    private string statusMessage = "";
+
+    void HandleFile(InputFileChangeEventArgs args) { }
+
+    async Task Upload()
+    {
+        if (fileUpload.HasFile)
+        {
+            var fileName = fileUpload.FileName;
+            var savePath = Path.Combine(Environment.WebRootPath, "uploads", fileName);
+            await fileUpload.SaveAs(savePath);
+            statusMessage = "File uploaded: " + fileName;
+        }
+    }
+}
+
+
+

Security Consideration

+

Always validate uploaded files on the server side. The Accept attribute only provides client-side filtering and can be bypassed. Validate file extensions, content types, and file sizes before saving. The SaveAllFiles method sanitizes filenames using Path.GetFileName to prevent directory traversal attacks, but additional validation is recommended.

+
+
+

File Size Limits

+

The default MaxFileSize is 512,000 bytes (~500 KiB). For larger files, increase this value. Be mindful that large files consume memory, especially when using FileBytes or GetFileBytesAsync(). For very large files, work with the FileContent stream directly.

+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/HiddenField/index.html b/site/EditorControls/HiddenField/index.html new file mode 100644 index 000000000..63b795aa5 --- /dev/null +++ b/site/EditorControls/HiddenField/index.html @@ -0,0 +1,4785 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + HiddenField - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

HiddenField

+

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.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.hiddenfield?view=netframework-4.8

+

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
    • +
+

Syntax Comparison

+
+
+
+
<asp:HiddenField
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    OnValueChanged="ValueChanged event handler"
+    runat="server"
+    SkinID="string"
+    Value="string"
+    Visible="True|False"
+/>
+
+
+
+
<HiddenField ID="myHiddenField" Value="@secretValue" />
+
+@code {
+    private string secretValue = "stored-data-123";
+}
+
+
+
+
+

With Value Changed Event

+
<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: +

<HiddenField ID="myHidden" Value="secret123" />
+

+

Rendered 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. +
  2. Remove EnableViewState and EnableTheming - Not applicable in Blazor
    3. +
  3. Replace lifecycle events - Use Blazor lifecycle methods instead
    4. +
  4. Consider alternatives - For pure Blazor apps, you may not need HiddenField; use component state or @bind instead
    5. +
  5. JavaScript interop - HiddenField is still useful when you need to exchange values with JavaScript
    6. +
+
+

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

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Image/index.html b/site/EditorControls/Image/index.html new file mode 100644 index 000000000..39b4aea11 --- /dev/null +++ b/site/EditorControls/Image/index.html @@ -0,0 +1,5114 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Image - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Image

+

The Image component displays an image on a web page. It may seem strange that we have an Image component when there already is an HTML <img> element and Blazor has features that enable C# interactions with that image, but we need to activate other features that were once present in Web Forms, such as DescriptionUrl for accessibility, ImageAlign for legacy alignment, and GenerateEmptyAlternateText for accessibility compliance.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.image?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • AlternateText - alternate text displayed when the image is unavailable (renders as alt attribute)
    • +
  • DescriptionUrl - the location to a detailed description for the image (renders as longdesc attribute)
    • +
  • GenerateEmptyAlternateText - when true, generates an empty alt="" attribute for decorative images (accessibility compliance)
    • +
  • ImageAlign - the alignment of the image in relation to other elements on the Web page (renders as align attribute)
    • +
  • ImageUrl - the URL of the image to display (renders as src attribute)
    • +
  • ToolTip - tooltip text displayed on hover (renders as title attribute)
    • +
  • Visible - controls image visibility
    • +
+

Blazor Notes

+
    +
  • The ImageUrl property maps directly to the HTML src attribute. In Blazor, you can use relative paths from your wwwroot folder (e.g., /images/logo.png) or absolute URLs
    • +
  • For static assets in Blazor, place images in the wwwroot folder and reference them with a leading /
    • +
  • The ImageAlign property uses the ImageAlign enum with values: NotSet, Left, Right, Baseline, Top, Middle, Bottom, AbsBottom, AbsMiddle, TextTop
    • +
  • The longdesc attribute (from DescriptionUrl) is considered obsolete in HTML5 but is rendered for backward compatibility. Consider using aria-describedby in new applications
    • +
+

Web Forms Features NOT Supported

+
    +
  • Style properties (BackColor, ForeColor, BorderColor, BorderStyle, BorderWidth, CssClass, Width, Height, Font) - Not yet implemented; use standard HTML/CSS styling on a wrapper element
    • +
  • AccessKey - Not supported; use HTML accesskey attribute directly if needed
    • +
  • TabIndex - Not supported; use HTML tabindex attribute directly if needed
    • +
  • EnableTheming/SkinID - Not supported; ASP.NET theming is not available in Blazor
    • +
  • EnableViewState - Not needed; Blazor manages state differently
    • +
  • Lifecycle events (OnDataBinding, OnInit, OnLoad, etc.) - Not supported; use Blazor lifecycle methods instead
    • +
+

Syntax Comparison

+
+
+
+
<asp:Image
+    AccessKey="string"
+    AlternateText="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    DescriptionUrl="uri"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ForeColor="color name|#dddddd"
+    GenerateEmptyAlternateText="True|False"
+    Height="size"
+    ID="string"
+    ImageAlign="NotSet|Left|Right|Baseline|Top|Middle|Bottom|
+        AbsBottom|AbsMiddle|TextTop"
+    ImageUrl="uri"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<Image ImageUrl="/images/photo.jpg" AlternateText="A beautiful photo" />
+
+
+
+
+

Image with Tooltip

+
<Image ImageUrl="/images/logo.png" 
+       AlternateText="Company Logo" 
+       ToolTip="Our company logo" />
+
+

Image with Alignment

+
@using BlazorWebFormsComponents.Enums
+
+<Image ImageUrl="/images/icon.png" 
+       AlternateText="Icon" 
+       ImageAlign="ImageAlign.Left" />
+<p>This text flows around the left-aligned image.</p>
+
+

Decorative Image (Empty Alt Text)

+
<Image ImageUrl="/images/decorative-border.png" 
+       GenerateEmptyAlternateText="true" />
+
+

Image with Description URL

+
<Image ImageUrl="/images/complex-chart.png" 
+       AlternateText="Sales Chart" 
+       DescriptionUrl="/descriptions/sales-chart.html" />
+
+

HTML Output

+

Blazor Input: +

<Image ImageUrl="/images/photo.jpg" 
+       AlternateText="A photo" 
+       ToolTip="Click to enlarge" 
+       ImageAlign="ImageAlign.Left" />
+

+

Rendered HTML: +

<img src="/images/photo.jpg" alt="A photo" longdesc="" title="Click to enlarge" align="left" />
+

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove asp: prefix - Change <asp:Image> to <Image>
    2. +
  2. Remove runat="server" - Not needed in Blazor
    3. +
  3. Remove ID attribute - Use @ref if you need a reference to the component
    4. +
  4. Update image paths - Place images in wwwroot folder and use paths like /images/photo.jpg
    5. +
  5. Add @using for enums - Add @using BlazorWebFormsComponents.Enums when using ImageAlign
    6. +
  6. Style properties - Wrap the Image in a <div> or <span> and apply CSS for styling not yet supported
    7. +
+

Before (Web Forms)

+
<asp:Image ID="imgLogo" 
+           ImageUrl="~/images/logo.png" 
+           AlternateText="Company Logo"
+           CssClass="logo-image"
+           runat="server" />
+
+

After (Blazor)

+
<div class="logo-image">
+    <Image ImageUrl="/images/logo.png" 
+           AlternateText="Company Logo" />
+</div>
+
+

Examples

+

Basic Image Display

+
<Image ImageUrl="/images/sample.jpg" AlternateText="Sample Image" />
+
+

Dynamic Image URL

+
<Image ImageUrl="@imageUrl" AlternateText="@imageAlt" />
+
+@code {
+    private string imageUrl = "/images/default.png";
+    private string imageAlt = "Default image";
+
+    void ChangeImage()
+    {
+        imageUrl = "/images/alternate.png";
+        imageAlt = "Alternate image";
+    }
+}
+
+

Conditional Visibility

+
<Image ImageUrl="/images/banner.jpg" 
+       AlternateText="Promotional Banner" 
+       Visible="@showBanner" />
+
+<button @onclick="ToggleBanner">Toggle Banner</button>
+
+@code {
+    private bool showBanner = true;
+
+    void ToggleBanner()
+    {
+        showBanner = !showBanner;
+    }
+}
+
+

Text Wrapping with Aligned Image

+
@using BlazorWebFormsComponents.Enums
+
+<Image ImageUrl="/images/author.jpg" 
+       AlternateText="Author photo" 
+       ImageAlign="ImageAlign.Left" />
+
+<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
+   This text wraps around the left-aligned image. The ImageAlign 
+   property allows you to control how content flows around the image.</p>
+
+<div style="clear: both;"></div>
+
+

See Also

+
    +
  • ImageButton - A clickable image that acts as a button
    • +
  • HyperLink - Wrap an Image in a HyperLink for clickable images
    • +
  • Live Demo - Interactive Image samples
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/ImageButton/index.html b/site/EditorControls/ImageButton/index.html new file mode 100644 index 000000000..2f1177f6b --- /dev/null +++ b/site/EditorControls/ImageButton/index.html @@ -0,0 +1,4644 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ImageButton - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ImageButton

+ +

It may seem strange that we have a ImageButton component when there already is an HTML input with image type and Blazor has features that enable C# interactions with that image, 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.imagebutton?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • AlternateText alternate text displayed when the image is unavailable
    • +
  • DescriptionUrl the location to a detailed description for the image
    • +
  • ImageAlign the alignment of the image in relation to other elements on the Web page
    • +
  • ImageUrl The URL of the image
    • +
  • OnClick event handler
    • +
  • OnClientClick JavaScript pointer
    • +
  • OnCommand event handler with event bubbling
    • +
  • PostBackurl The URL of the Web page to post to from the current page
    • +
+

Syntax Comparison

+
+
+
+
<asp:ImageButton
+    AccessKey="string"
+    AlternateText="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CausesValidation="True|False"
+    CommandArgument="string"
+    CommandName="string"
+    CssClass="string"
+    DescriptionUrl="uri"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    ImageAlign="NotSet|Left|Right|Baseline|Top|Middle|Bottom|
+        AbsBottom|AbsMiddle|TextTop"
+    ImageUrl="uri"
+    OnClick="Click event handler"
+    OnClientClick="string"
+    OnCommand="Command event handler"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    PostBackUrl="uri"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    ToolTip="string"
+    ValidationGroup="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<ImageButton
+    ImageUrl="/images/submit-btn.png"
+    AlternateText="Submit Form"
+    DescriptionUrl="/descriptions/submit.html"
+    ImageAlign="Middle"
+    OnClick="HandleClick"
+    OnClientClick="return confirm('Submit?');"
+    CommandName="Submit"
+    CommandArgument="formData"
+    OnCommand="HandleCommand"
+    PostBackUrl="/results"
+    CssClass="img-btn" />
+
+@code {
+    private void HandleClick(ImageClickEventArgs e)
+    {
+        // e.X and e.Y contain click coordinates
+    }
+
+    private void HandleCommand(CommandEventArgs e)
+    {
+        var name = e.CommandName;    // "Submit"
+        var arg = e.CommandArgument;  // "formData"
+    }
+}
+
+
+
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Label/index.html b/site/EditorControls/Label/index.html new file mode 100644 index 000000000..6f9e82b9f --- /dev/null +++ b/site/EditorControls/Label/index.html @@ -0,0 +1,5136 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Label - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Label

+

The Label component displays a text label. While HTML has native <label> and <span> elements, the BWFC Label component emulates the ASP.NET Web Forms <asp:Label> control, enabling features like styling, the AssociatedControlID property for accessibility, and a familiar API for Web Forms developers.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.label?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • Text — The text content displayed by the label
    • +
  • AssociatedControlID — Associates the label with a form control using the for attribute (improves accessibility)
    • +
  • ToolTip — Tooltip text displayed on hover (renders as title attribute)
    • +
  • Visible — Controls whether the label is rendered
    • +
  • Enabled — Enable or disable the label
    • +
  • All style properties (BackColor, ForeColor, BorderColor, BorderStyle, BorderWidth, CssClass, Width, Height, Font)
    • +
  • AccessKey — Keyboard shortcut key
    • +
  • TabIndex — Tab order
    • +
  • ID — Control identifier rendered in HTML
    • +
+

Web Forms Features NOT Supported

+
    +
  • EnableViewState — Not applicable in Blazor
    • +
  • EnableTheming — Partially supported; theme system works differently in Blazor
    • +
  • SkinID — Limited support compared to Web Forms themes
    • +
  • OnDataBinding, OnInit, OnLoad, OnPreRender, OnUnload — Blazor lifecycle differs from Web Forms
    • +
+

Syntax Comparison

+
+
+
+
<asp:Label
+    AccessKey="string"
+    AssociatedControlID="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    Enabled="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Size="string"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    runat="server"
+    TabIndex="integer"
+    Text="string"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<Label
+    AccessKey="string"
+    AssociatedControlID="string"
+    BackColor="WebColor.Color"
+    BorderColor="WebColor.Color"
+    BorderStyle="BorderStyle.Solid"
+    BorderWidth="1px"
+    CssClass="string"
+    Enabled="true"
+    Font="new FontInfo() { Bold = true }"
+    ForeColor="WebColor.Black"
+    Height="20px"
+    ID="string"
+    TabIndex="0"
+    Text="string"
+    ToolTip="string"
+    Visible="true"
+    Width="200px"
+/>
+
+
+
+
+

Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
TextstringnullText content of the label
AssociatedControlIDstringnullID of the control to associate with (renders <label for="">)
ToolTipstringnullHover text
VisiblebooltrueShow or hide the label
EnabledbooltrueEnable or disable the label
BackColorWebColordefaultBackground color
ForeColorWebColordefaultText color
BorderColorWebColordefaultBorder color
BorderStyleBorderStyleNotSetBorder style
BorderWidthUnitdefaultBorder width
CssClassstringnullCSS class(es)
WidthUnitdefaultControl width
HeightUnitdefaultControl height
FontFontInfonew FontInfo()Font properties (Bold, Italic, Name, Size, etc.)
AccessKeystringnullKeyboard shortcut key
TabIndexshort0Tab order
IDstringnullControl identifier
+

HTML Output

+

When AssociatedControlID is set, the label renders as an HTML <label> tag with a for attribute:

+
<!-- Blazor Input -->
+<Label Text="Email Address" AssociatedControlID="emailInput" />
+
+<!-- Rendered HTML -->
+<label for="emailInput">Email Address</label>
+
+

When AssociatedControlID is not set, it renders as a <span>:

+
<!-- Blazor Input -->
+<Label Text="Welcome" />
+
+<!-- Rendered HTML -->
+<span>Welcome</span>
+
+

With styling:

+
<!-- Blazor Input -->
+<Label Text="Important"
+        BackColor="WebColor.Yellow"
+        ForeColor="WebColor.Red"
+        Font_Bold="true" />
+
+<!-- Rendered HTML -->
+<span style="background-color:Yellow;color:Red;font-weight:bold;">Important</span>
+
+

Examples

+

Basic Label

+
<Label Text="Full Name:" />
+
+

Label Associated with Input

+

Improves accessibility by linking the label to a form control:

+
<Label Text="Email Address:" AssociatedControlID="emailInput" />
+<InputText id="emailInput" @bind-Value="model.Email" />
+
+

Styled Label

+
<Label Text="Warning"
+        ForeColor="WebColor.Red"
+        Font_Bold="true"
+        CssClass="warning-label" />
+
+

Label with Tooltip

+
<Label Text="Username"
+        ToolTip="Your login username (case-sensitive)" />
+
+

Conditional Visibility

+
<Label Text="Validation Error" 
+        ForeColor="WebColor.Red"
+        Visible="@showError" />
+
+@code {
+    private bool showError = false;
+}
+
+

Label with Border

+
<Label Text="Important Notice"
+        BorderColor="WebColor.Black"
+        BorderStyle="BorderStyle.Solid"
+        BorderWidth="2px"
+        BackColor="WebColor.LightYellow"
+        CssClass="notice-box" />
+
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove asp: prefix — Change <asp:Label> to <Label>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Text property name stays the same — Direct property instead of inline content
    4. +
  4. AssociatedControlID works the same — Maintains accessibility pattern
    5. +
  5. Font properties use FontInfo object — Instead of hyphenated attributes like Font-Bold
    6. +
  6. Style properties use enums — e.g., BorderStyle.Solid instead of string values
    7. +
  7. Colors use WebColor enum — Instead of color name strings
    8. +
+

Migration Example

+
+
+
+
<asp:Label ID="lblEmail"
+           Text="Email Address:"
+           AssociatedControlID="txtEmail"
+           ForeColor="Red"
+           Font-Bold="true"
+           runat="server" />
+<asp:TextBox ID="txtEmail" runat="server" />
+
+
+
+
<Label ID="lblEmail"
+       Text="Email Address:"
+       AssociatedControlID="txtEmail"
+       ForeColor="WebColor.Red"
+       Font="new FontInfo() { Bold = true }" />
+<InputText id="txtEmail" @bind-Value="model.Email" />
+
+
+
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/LinkButton/index.html b/site/EditorControls/LinkButton/index.html new file mode 100644 index 000000000..7eb2cf3f8 --- /dev/null +++ b/site/EditorControls/LinkButton/index.html @@ -0,0 +1,4642 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + LinkButton - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

LinkButton

+ +

It may seem strange that we have a LinkButton component when there already is an HTML anchor and Blazor has features that enable C# interactions with that link, 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.linkbutton?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • OnClick event handler
    • +
  • OnClientClick JavaScript pointer
    • +
  • OnCommand event handler with event bubbling
    • +
  • PostBackurl The URL of the Web page to post to from the current page
    • +
+

Syntax Comparison

+
+
+
+
<asp:LinkButton
+    AccessKey="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CausesValidation="True|False"
+    CommandArgument="string"
+    CommandName="string"
+    CssClass="string"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    OnClick="Click event handler"
+    OnClientClick="string"
+    OnCommand="Command event handler"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    PostBackUrl="uri"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    Text="string"
+    ToolTip="string"
+    ValidationGroup="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<LinkButton
+    Text="Click Me"
+    OnClick="HandleClick"
+    OnClientClick="return confirm('Are you sure?');"
+    CommandName="Select"
+    CommandArgument="42"
+    OnCommand="HandleCommand"
+    PostBackUrl="/target-page"
+    CssClass="link-btn" />
+
+@code {
+    private void HandleClick(EventArgs e)
+    {
+        // Handle click event
+    }
+
+    private void HandleCommand(CommandEventArgs e)
+    {
+        var name = e.CommandName;    // "Select"
+        var arg = e.CommandArgument;  // "42"
+    }
+}
+
+
+
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/ListBox/index.html b/site/EditorControls/ListBox/index.html new file mode 100644 index 000000000..f2cbbdbb2 --- /dev/null +++ b/site/EditorControls/ListBox/index.html @@ -0,0 +1,5241 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ListBox - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ListBox

+

The ListBox component renders an HTML <select> element with a size attribute that displays multiple rows, allowing users to select one or more items from a list. This component supports both static items and data-bound scenarios.

+

Original Web Forms documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.listbox?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Static items via StaticItems parameter with ListItem collection
    • +
  • Data binding via Items parameter with DataTextField and DataValueField
    • +
  • Two-way binding with @bind-SelectedValue and @bind-SelectedValues
    • +
  • Rows property controls visible row count (maps to size attribute)
    • +
  • Single or Multiple selection modes via SelectionMode parameter
    • +
  • Selected item tracking via SelectedValue, SelectedValues, and SelectedIndex
    • +
  • OnSelectedIndexChanged event handler
    • +
  • Disabled state via Enabled parameter
    • +
  • Disabled items via ListItem.Enabled property
    • +
  • Style attributes (BackColor, ForeColor, Font, etc.) and CssClass formatting
    • +
  • Access to SelectedItem and SelectedItems properties
    • +
+

WebForms Features Not Supported

+
    +
  • AutoPostBack is not supported in Blazor - use OnSelectedIndexChanged event instead
    • +
  • AppendDataBoundItems is not implemented
    • +
  • DataSourceID is not supported - bind directly to collections via Items parameter
    • +
+

Syntax Comparison

+
+
+
+
<asp:ListBox
+    AccessKey="string"
+    AutoPostBack="True|False"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    DataSourceID="string"
+    DataTextField="string"
+    DataValueField="string"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnSelectedIndexChanged="SelectedIndexChanged event handler"
+    OnUnload="Unload event handler"
+    Rows="integer"
+    runat="server"
+    SelectionMode="Single|Multiple"
+    SelectedIndex="integer"
+    SelectedValue="string"
+    TabIndex="integer"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size">
+
+    <asp:ListItem Value="value1" Text="Display Text 1" Selected="True|False" />
+    <asp:ListItem Value="value2" Text="Display Text 2" />
+
+</asp:ListBox>
+
+
+
+
<ListBox TItem="object" StaticItems="items" @bind-SelectedValue="selectedValue" />
+
+@code {
+    private string selectedValue = "";
+
+    private ListItemCollection items = new()
+    {
+        new ListItem("Apple", "1"),
+        new ListItem("Banana", "2"),
+        new ListItem("Cherry", "3"),
+        new ListItem("Date", "4")
+    };
+}
+
+
+
+
+

Multiple Selection

+
@using BlazorWebFormsComponents.Enums
+
+<ListBox TItem="object"
+         StaticItems="items"
+         SelectionMode="ListSelectionMode.Multiple"
+         @bind-SelectedValues="selectedValues" />
+
+@code {
+    private List<string> selectedValues = new();
+
+    private ListItemCollection items = new()
+    {
+        new ListItem("Red", "r"),
+        new ListItem("Green", "g"),
+        new ListItem("Blue", "b")
+    };
+}
+
+

Custom Row Count

+
<ListBox TItem="object" StaticItems="items" Rows="6" @bind-SelectedValue="selectedValue" />
+
+

Data Binding

+
<ListBox TItem="Product"
+         Items="products"
+         DataTextField="Name"
+         DataValueField="Id"
+         @bind-SelectedValue="selectedProductId" />
+
+@code {
+    private string selectedProductId = "";
+
+    private List<Product> products = new()
+    {
+        new Product { Id = "1", Name = "Widget" },
+        new Product { Id = "2", Name = "Gadget" },
+        new Product { Id = "3", Name = "Gizmo" }
+    };
+
+    public class Product
+    {
+        public string Id { get; set; }
+        public string Name { get; set; }
+    }
+}
+
+

With Event Handler

+
<ListBox TItem="object"
+         StaticItems="items"
+         @bind-SelectedValue="selectedValue"
+         OnSelectedIndexChanged="HandleSelectionChanged" />
+
+@code {
+    private string selectedValue = "";
+
+    private void HandleSelectionChanged(ChangeEventArgs e)
+    {
+        var newValue = e.Value?.ToString();
+        Console.WriteLine($"Selection changed to: {newValue}");
+    }
+}
+
+

With Styling

+
<ListBox TItem="object"
+         StaticItems="items"
+         CssClass="form-select"
+         BackColor="new WebColor(System.Drawing.Color.LightYellow)"
+         Font="new FontInfo { Bold = true }" />
+
+

Key Differences from Web Forms

+
    +
  1. Type Parameter: Blazor ListBox requires a TItem type parameter for data binding
    2. +
  2. Property Names: Use StaticItems for the item collection (not Items), as Items is reserved for data-bound scenarios
    3. +
  3. Two-way Binding: Use @bind-SelectedValue or @bind-SelectedValues for automatic two-way binding
    4. +
  4. Events: Use OnSelectedIndexChanged with ChangeEventArgs instead of specialized event args
    5. +
  5. No AutoPostBack: Blazor's event model doesn't require postback; events fire immediately
    6. +
  6. Selection Mode Enum: Use ListSelectionMode.Single or ListSelectionMode.Multiple from BlazorWebFormsComponents.Enums
    7. +
+

Key Differences from DropDownList

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureDropDownListListBox
DisplaySingle visible rowMultiple rows (size attribute)
SelectionSingle onlySingle or Multiple
HTML<select><select size="N">
MultipleNot supported<select multiple> via SelectionMode
RowsN/AConfigurable via Rows property
+

ListItem and ListItemCollection

+

The ListItem class represents individual items in the listbox:

+
public class ListItem
+{
+    public string Text { get; set; }
+    public string Value { get; set; }
+    public bool Selected { get; set; }
+    public bool Enabled { get; set; } = true;
+
+    public ListItem(string text)
+    public ListItem(string text, string value)
+    public ListItem(string text, string value, bool selected)
+}
+
+

The ListItemCollection class provides helper methods:

+
public class ListItemCollection : List<ListItem>
+{
+    public ListItem FindByValue(string value)
+    public ListItem FindByText(string text)
+}
+
+

ListSelectionMode Enum

+
public enum ListSelectionMode
+{
+    Single,    // Only one item can be selected
+    Multiple   // Multiple items can be selected
+}
+
+

Common Patterns

+

Pre-select an Item

+
<ListBox TItem="object" StaticItems="items" SelectedValue="2" />
+
+

Pre-select Multiple Items

+
<ListBox TItem="object"
+         StaticItems="items"
+         SelectionMode="ListSelectionMode.Multiple"
+         SelectedValues="@(new List<string> { "1", "3" })" />
+
+

Disabled ListBox

+
<ListBox TItem="object" StaticItems="items" Enabled="false" />
+
+

Disabled Individual Items

+
@code {
+    private ListItemCollection items = new()
+    {
+        new ListItem("Available", "1") { Enabled = true },
+        new ListItem("Unavailable", "2") { Enabled = false }
+    };
+}
+
+

Get Selected Item Details

+
var listbox = // reference to ListBox component
+
+// Single selection
+var selectedItem = listbox.SelectedItem;
+var text = selectedItem?.Text;
+var value = selectedItem?.Value;
+
+// Multiple selection
+foreach (var item in listbox.SelectedItems)
+{
+    Console.WriteLine($"{item.Text}: {item.Value}");
+}
+
+

Migration Tips

+

When migrating from Web Forms:

+
    +
  1. Replace <asp:ListBox> with <ListBox TItem="object">
    2. +
  2. Rename any Items parameter to StaticItems
    3. +
  3. Replace AutoPostBack="true" with OnSelectedIndexChanged event handler
    4. +
  4. Use @bind-SelectedValue or @bind-SelectedValues instead of manually managing selection
    5. +
  5. Remove runat="server" attribute
    6. +
  6. Remove <asp:ListItem> tags and define items in code-behind as ListItemCollection
    7. +
  7. Add @using BlazorWebFormsComponents.Enums if using SelectionMode
    8. +
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Literal/index.html b/site/EditorControls/Literal/index.html new file mode 100644 index 000000000..f240d11e7 --- /dev/null +++ b/site/EditorControls/Literal/index.html @@ -0,0 +1,4572 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Literal - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Literal

+ +

The Literal component is meant to emulate the asp:Literal control in markup and is defined in the https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.literal?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Mode specifies how the content in the Literal component is rendered
    • +
  • Text the text content of the Literal component
    • +
+

Syntax Comparison

+
+
+
+
<asp:Literal
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    Mode="Transform|PassThrough|Encode"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    SkinID="string"
+    Text="string"
+    Visible="True|False"
+/>
+
+
+
+
<!-- Render raw HTML content -->
+<Literal Text="Hello, <strong>World</strong>!" Mode="PassThrough" />
+
+<!-- HTML-encode the output for safe display -->
+<Literal Text="<script>alert('xss')</script>" Mode="Encode" />
+
+<!-- Dynamic text from code -->
+<Literal Text="@message" />
+
+@code {
+    private string message = "Welcome to <em>Blazor</em>!";
+}
+
+
+
+
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Localize/index.html b/site/EditorControls/Localize/index.html new file mode 100644 index 000000000..889475c24 --- /dev/null +++ b/site/EditorControls/Localize/index.html @@ -0,0 +1,4875 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Localize - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Localize

+

The Localize component emulates the ASP.NET Web Forms asp:Localize control. In Web Forms, Localize inherits directly from Literal and is functionally identical to it — the only difference is semantic. Localize marks text as localizable for design-time tooling and resource expression support (<%$ Resources:... %>). In Blazor, there is no design-time localization distinction, so this component exists purely for markup compatibility during migration.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.localize?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • Text - the text content to display (pass localized strings from IStringLocalizer<T>)
    • +
  • Mode - specifies how the content is rendered (Encode, PassThrough, or Transform)
    • +
  • Visible - controls whether the text is rendered
    • +
+

Blazor Notes

+
    +
  • Localize inherits from Literal and behaves identically. All properties, rendering, and modes are inherited.
    • +
  • No wrapper HTML element is rendered — the text is output directly into the DOM.
    • +
  • When Mode is Encode (the default), text is HTML-encoded. When Mode is PassThrough, text is rendered as raw markup.
    • +
+
+

Localization in Blazor

+

In Web Forms, Localize enabled design-time localization via resource expressions like <%$ Resources:MyResource, MyKey %>. Blazor does not have resource expressions. Instead, inject IStringLocalizer<T> and pass localized strings to the Text property. See Microsoft's Blazor globalization documentation for details.

+
+

Web Forms Features NOT Supported

+
    +
  • Resource Expressions (<%$ Resources:... %>) - Not supported in Blazor; use IStringLocalizer<T> instead
    • +
  • Design-time localization tooling - No Blazor equivalent; localization is handled at runtime via .NET localization APIs
    • +
  • EnableTheming / SkinID - Theming is not supported in Blazor
    • +
+

Syntax Comparison

+
+
+
+
<asp:Localize
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    Mode="Transform|PassThrough|Encode"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    SkinID="string"
+    Text="string"
+    Visible="True|False"
+/>
+
+
+
+
<Localize Text="Hello, World!" />
+
+
+
+
+

With Localized Text

+
@inject IStringLocalizer<MyPage> Localizer
+
+<Localize Text="@Localizer["WelcomeMessage"]" />
+
+

With Mode

+
<Localize Text="<strong>Bold text</strong>" Mode="LiteralMode.PassThrough" />
+<Localize Text="<script>alert('safe')</script>" Mode="LiteralMode.Encode" />
+
+

HTML Output

+

Localize renders no wrapper HTML element — text is output directly into the DOM, identical to Literal.

+

Blazor Input: +

<Localize Text="Hello, World!" />
+

+

Rendered HTML: +

Hello, World!
+

+

With Mode=PassThrough: +

<Localize Text="<em>emphasized</em>" Mode="LiteralMode.PassThrough" />
+

+

Rendered HTML: +

<em>emphasized</em>
+

+

With Mode=Encode (default): +

<Localize Text="<em>encoded</em>" Mode="LiteralMode.Encode" />
+

+

Rendered HTML: +

&lt;em&gt;encoded&lt;/em&gt;
+

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove asp: prefix - Change <asp:Localize> to <Localize>
    2. +
  2. Remove runat="server" - Not needed in Blazor
    3. +
  3. Replace resource expressions - Replace <%$ Resources:MyResource, MyKey %> with IStringLocalizer<T> injection
    4. +
  4. Static text - If the Text was hardcoded, no additional changes are needed
    5. +
+

Before (Web Forms)

+
<asp:Localize ID="lblWelcome"
+              Text="<%$ Resources:Messages, WelcomeText %>"
+              Mode="Encode"
+              runat="server" />
+
+

After (Blazor)

+
@inject IStringLocalizer<MyPage> Localizer
+
+<Localize Text="@Localizer["WelcomeText"]" Mode="LiteralMode.Encode" />
+
+
+

Consider Using Literal

+

Since Localize is identical to Literal in Blazor, you can use either component interchangeably. If you are writing new Blazor code (not migrating), Literal is the conventional choice. Use Localize when migrating existing markup that already uses <asp:Localize> to minimize changes.

+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/MasterPage/index.html b/site/EditorControls/MasterPage/index.html new file mode 100644 index 000000000..846b68883 --- /dev/null +++ b/site/EditorControls/MasterPage/index.html @@ -0,0 +1,5209 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MasterPage - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

MasterPage

+

The MasterPage component emulates the ASP.NET Web Forms <asp:MasterPage> directive and provides master page template functionality in Blazor. A MasterPage defines a consistent layout and structure across pages, with customizable regions defined by ContentPlaceHolder components. Child pages inject content using Content controls.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.masterpage

+

Features Supported in Blazor

+
    +
  • ChildContent — the master page template layout containing ContentPlaceHolder controls
    • +
  • Head — optional head content automatically wrapped in HeadContent component (for <title>, <meta>, <link>, etc.)
    • +
  • Visible — controls whether the entire master page is rendered
    • +
  • Content and ContentPlaceHolder registration and management
    • +
  • Support for multiple content sections via named ContentPlaceHolders
    • +
  • Automatic <title> element handling in Head content
    • +
+

Web Forms Features NOT Supported

+
    +
  • Title property — use Blazor's PageTitle component or @page directive instead
    • +
  • MasterPageFile property — nested master pages use nested layouts instead
    • +
  • Direct theme/skin support — use CSS styling instead
    • +
+

Syntax Comparison

+
+
+
+
<!-- Site.Master -->
+<%@ Master Language="C#" %>
+<!DOCTYPE html>
+<html>
+<head runat="server">
+    <title>My Site</title>
+    <link rel="stylesheet" href="~/css/site.css" />
+</head>
+<body>
+    <form runat="server">
+        <div class="header">
+            <h1>My Website</h1>
+        </div>
+
+        <asp:ContentPlaceHolder ID="MainContent" runat="server">
+            <p>Default content</p>
+        </asp:ContentPlaceHolder>
+
+        <div class="footer">
+            <p>&copy; 2024 My Company</p>
+        </div>
+    </form>
+</body>
+</html>
+
+<!-- MyPage.aspx -->
+<%@ Page Title="Home" Language="C#" MasterPageFile="~/Site.Master" %>
+
+<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server">
+    <h2>Welcome to my page!</h2>
+</asp:Content>
+
+
+
+
<!-- MasterLayout.razor -->
+<MasterPage>
+    <Head>
+        <title>My Site</title>
+        <link rel="stylesheet" href="css/site.css" />
+    </Head>
+
+    <ChildContent>
+        <div class="header">
+            <h1>My Website</h1>
+        </div>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>Default content</p>
+        </ContentPlaceHolder>
+
+        <div class="footer">
+            <p>&copy; 2024 My Company</p>
+        </div>
+    </ChildContent>
+</MasterPage>
+
+<!-- MyPage.razor -->
+<MasterPage>
+    <Head>
+        <title>My Site - Home</title>
+        <link rel="stylesheet" href="css/site.css" />
+    </Head>
+
+    <ChildContent>
+        <div class="header">
+            <h1>My Website</h1>
+        </div>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>Default content</p>
+        </ContentPlaceHolder>
+
+        <div class="footer">
+            <p>&copy; 2024 My Company</p>
+        </div>
+    </ChildContent>
+
+    <Content ContentPlaceHolderID="MainContent">
+        <h2>Welcome to my page!</h2>
+    </Content>
+</MasterPage>
+
+
+
+
+

Blazor Usage Examples

+

Basic MasterPage with Layout Template

+
<MasterPage>
+    <ChildContent>
+        <div class="header">
+            <h1>My Website</h1>
+        </div>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>Default content</p>
+        </ContentPlaceHolder>
+
+        <div class="footer">
+            <p>&copy; 2024 My Company</p>
+        </div>
+    </ChildContent>
+</MasterPage>
+
+

MasterPage with Head Content

+

The Head parameter allows you to define head content (title, meta tags, stylesheets, etc.) that is rendered in the document's <head> section via HeadOutlet.

+
<MasterPage>
+    <Head>
+        <title>My Website - Home</title>
+        <meta name="description" content="My awesome website" />
+        <link rel="stylesheet" href="css/site.css" />
+    </Head>
+
+    <ChildContent>
+        <header>
+            <h1>My Website</h1>
+            <nav>
+                <a href="/">Home</a>
+                <a href="/about">About</a>
+            </nav>
+        </header>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>Default content goes here</p>
+        </ContentPlaceHolder>
+
+        <footer>
+            <p>&copy; 2024 My Company</p>
+        </footer>
+    </ChildContent>
+</MasterPage>
+
+

MasterPage with Multiple Content Sections

+
<MasterPage>
+    <Head>
+        <title>My Site</title>
+    </Head>
+
+    <ChildContent>
+        <header>
+            <ContentPlaceHolder ID="PageTitle">
+                <h1>Default Title</h1>
+            </ContentPlaceHolder>
+        </header>
+
+        <aside>
+            <ContentPlaceHolder ID="Sidebar">
+                <nav>
+                    <ul>
+                        <li>Default Nav</li>
+                    </ul>
+                </nav>
+            </ContentPlaceHolder>
+        </aside>
+
+        <main>
+            <ContentPlaceHolder ID="MainContent">
+                <p>Default main content</p>
+            </ContentPlaceHolder>
+        </main>
+    </ChildContent>
+
+    <Content ContentPlaceHolderID="PageTitle">
+        <h1>Article Title</h1>
+    </Content>
+
+    <Content ContentPlaceHolderID="Sidebar">
+        <nav>
+            <ul>
+                <li><a href="/">Home</a></li>
+                <li><a href="/articles">Articles</a></li>
+            </ul>
+        </nav>
+    </Content>
+
+    <Content ContentPlaceHolderID="MainContent">
+        <article>
+            <p>Article content here</p>
+        </article>
+    </Content>
+</MasterPage>
+
+

MasterPage with Conditional Visibility

+
<MasterPage Visible="@isVisible">
+    <Head>
+        <title>Conditional Master</title>
+    </Head>
+
+    <ChildContent>
+        <header>
+            <h1>Site Header</h1>
+        </header>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>Content</p>
+        </ContentPlaceHolder>
+    </ChildContent>
+</MasterPage>
+
+@code {
+    private bool isVisible = true;
+}
+
+

HTML Output

+

MasterPage renders its ChildContent, with ContentPlaceHolder regions replaced by either Content provided by child pages or default ChildContent if no custom Content is provided. The Head content is rendered in the document's <head> section via HeadOutlet.

+

Blazor Input: +

<MasterPage>
+    <Head>
+        <title>My Site</title>
+    </Head>
+
+    <ChildContent>
+        <header>
+            <h1>Header</h1>
+        </header>
+        <ContentPlaceHolder ID="Main">
+            <p>Default</p>
+        </ContentPlaceHolder>
+    </ChildContent>
+
+    <Content ContentPlaceHolderID="Main">
+        <p>Custom</p>
+    </Content>
+</MasterPage>
+

+

Rendered HTML: +

<!-- In <head> -->
+<title>My Site</title>
+
+<!-- In <body> -->
+<header>
+    <h1>Header</h1>
+</header>
+<p>Custom</p>
+

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDefaultDescription
ChildContentRenderFragmentnullThe master page template layout containing ContentPlaceHolder controls
HeadRenderFragmentnullOptional head content (title, meta, link, etc.) to be rendered in the document's <head> section via HeadOutlet
VisiblebooltrueControls whether the entire master page is rendered (inherited from BaseWebFormsComponent)
+

Obsolete Parameters

+

The following parameters exist for backward compatibility but are obsolete in Blazor:

+ + + + + + + + + + + + + + + + + + + + +
ParameterTypeNotes
TitlestringUse PageTitle component or @page directive instead
MasterPageFilestringNested layouts use the @layout directive in child layouts instead
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Rename Master file — Web Forms .Master files become .razor Blazor components
    2. +
  2. Remove directives — Remove <%@ Master %> and runat="server" attributes
    3. +
  3. Use Head parameter — Move <head runat="server"> content into the Head parameter
    4. +
  4. Use ChildContent — The template layout goes into the ChildContent parameter
    5. +
  5. Keep ID attributes — ContentPlaceHolder ID attributes work the same way
    6. +
  6. Nest Content controls — Content controls are placed as child components of the MasterPage
    7. +
  7. Set page title — Use PageTitle component in the Head section instead of ASP.NET's dynamic title setting
    8. +
+
+
+
+
<!-- Site.Master -->
+<%@ Master Language="C#" %>
+<!DOCTYPE html>
+<html>
+<head runat="server">
+    <title>My Site</title>
+    <link rel="stylesheet" href="~/css/site.css" />
+</head>
+<body>
+    <form runat="server">
+        <header>
+            <h1>My Website</h1>
+        </header>
+
+        <main>
+            <asp:ContentPlaceHolder ID="MainContent" runat="server">
+                <p>Default content</p>
+            </asp:ContentPlaceHolder>
+        </main>
+
+        <footer>
+            <p>&copy; 2024</p>
+        </footer>
+    </form>
+</body>
+</html>
+
+<!-- MyPage.aspx -->
+<%@ Page Title="Home" MasterPageFile="~/Site.Master" %>
+
+<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server">
+    <h2>Welcome!</h2>
+    <p>This is my page.</p>
+</asp:Content>
+
+
+
+
<!-- MasterLayout.razor -->
+<MasterPage>
+    <Head>
+        <title>My Site</title>
+        <link rel="stylesheet" href="css/site.css" />
+    </Head>
+
+    <ChildContent>
+        <header>
+            <h1>My Website</h1>
+        </header>
+
+        <main>
+            <ContentPlaceHolder ID="MainContent">
+                <p>Default content</p>
+            </ContentPlaceHolder>
+        </main>
+
+        <footer>
+            <p>&copy; 2024</p>
+        </footer>
+    </ChildContent>
+</MasterPage>
+
+<!-- MyPage.razor -->
+<MasterPage>
+    <Head>
+        <title>My Site - Home</title>
+        <link rel="stylesheet" href="css/site.css" />
+    </Head>
+
+    <ChildContent>
+        <header>
+            <h1>My Website</h1>
+        </header>
+
+        <main>
+            <ContentPlaceHolder ID="MainContent">
+                <p>Default content</p>
+            </ContentPlaceHolder>
+        </main>
+
+        <footer>
+            <p>&copy; 2024</p>
+        </footer>
+    </ChildContent>
+
+    <Content ContentPlaceHolderID="MainContent">
+        <h2>Welcome!</h2>
+        <p>This is my page.</p>
+    </Content>
+</MasterPage>
+
+
+
+
+

See Also

+
    +
  • Content — Provides content to fill ContentPlaceHolder regions
    • +
  • ContentPlaceHolder — Defines placeholder regions in master pages
    • +
  • Migration: Master Pages — Comprehensive master page migration guide
    • +
  • Blazor Layouts: documentation coming soon
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/MultiView/index.html b/site/EditorControls/MultiView/index.html new file mode 100644 index 000000000..464ca2044 --- /dev/null +++ b/site/EditorControls/MultiView/index.html @@ -0,0 +1,4845 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MultiView - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

MultiView / View

+

The MultiView and View components emulate the ASP.NET Web Forms asp:MultiView and asp:View controls. MultiView is a container that holds multiple View controls, displaying only one at a time based on the ActiveViewIndex property.

+

Original Microsoft documentation:

+
    +
  • MultiView: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.multiview?view=netframework-4.8
    • +
  • View: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.view?view=netframework-4.8
    • +
+

Blazor Features Supported

+

MultiView

+
    +
  • ActiveViewIndex — index of the currently visible View (-1 = none)
    • +
  • OnActiveViewChanged — event fired when the active view changes
    • +
  • GetActiveView() — returns the currently active View
    • +
  • SetActiveView(View) — sets the active view by reference
    • +
  • Command name constants: NextViewCommandName, PreviousViewCommandName, SwitchViewByIDCommandName, SwitchViewByIndexCommandName
    • +
  • Child View components auto-register via CascadingParameter
    • +
+

View

+
    +
  • ChildContent — arbitrary child content rendered when active
    • +
  • OnActivate — fired when this View becomes active
    • +
  • OnDeactivate — fired when this View is deactivated
    • +
  • Visible — controlled by parent MultiView
    • +
+

Web Forms Features NOT Supported

+
    +
  • Command-based navigation via BubbleEvent (use ActiveViewIndex binding instead)
    • +
  • EnableTheming / SkinID — theming not supported in Blazor
    • +
+

Syntax Comparison

+
+
+
+
<asp:MultiView ID="MultiView1" ActiveViewIndex="0" runat="server">
+    <asp:View ID="View1" runat="server">
+        <p>This is View 1</p>
+    </asp:View>
+    <asp:View ID="View2" runat="server">
+        <p>This is View 2</p>
+    </asp:View>
+</asp:MultiView>
+
+
+
+
<MultiView ActiveViewIndex="@activeIndex" OnActiveViewChanged="ViewChanged">
+    <View>
+        <p>This is View 1</p>
+        <Button Text="Next" OnClick="() => activeIndex = 1" />
+    </View>
+    <View>
+        <p>This is View 2</p>
+        <Button Text="Previous" OnClick="() => activeIndex = 0" />
+    </View>
+</MultiView>
+
+@code {
+    private int activeIndex = 0;
+
+    private void ViewChanged(EventArgs e)
+    {
+        // Handle view change
+    }
+}
+
+
+
+
+

HTML Output

+

MultiView and View render no wrapper HTML elements. Only the active View's child content is rendered directly into the DOM.

+

Blazor Input: +

<MultiView ActiveViewIndex="0">
+    <View><p>Hello</p></View>
+    <View><p>World</p></View>
+</MultiView>
+

+

Rendered HTML: +

<p>Hello</p>
+

+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:MultiView> to <MultiView> and <asp:View> to <View>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Bind ActiveViewIndex — Use @activeIndex binding instead of code-behind manipulation
    4. +
  4. Replace command navigation — Web Forms uses NextView/PrevView command names with Button controls. In Blazor, bind button clicks to change ActiveViewIndex directly.
    5. +
+

Before (Web Forms)

+
<asp:MultiView ID="MultiView1" ActiveViewIndex="0" runat="server">
+    <asp:View ID="View1" runat="server">
+        <asp:Button ID="btn1" CommandName="NextView" Text="Next" runat="server" />
+    </asp:View>
+    <asp:View ID="View2" runat="server">
+        <asp:Button ID="btn2" CommandName="PrevView" Text="Previous" runat="server" />
+    </asp:View>
+</asp:MultiView>
+
+

After (Blazor)

+
<MultiView ActiveViewIndex="@activeIndex">
+    <View>
+        <Button Text="Next" OnClick="() => activeIndex = 1" />
+    </View>
+    <View>
+        <Button Text="Previous" OnClick="() => activeIndex = 0" />
+    </View>
+</MultiView>
+
+@code {
+    private int activeIndex = 0;
+}
+
+

See Also

+
    +
  • Panel — Div-based container
    • +
  • View — Individual view within a MultiView
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Panel/index.html b/site/EditorControls/Panel/index.html new file mode 100644 index 000000000..ffd05b9e0 --- /dev/null +++ b/site/EditorControls/Panel/index.html @@ -0,0 +1,5235 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Panel - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Panel

+

The Panel component is a container control that renders as a <div> element, or as a <fieldset> when the GroupingText property is set. It provides a way to group controls and apply common styling.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.panel?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • Child content rendering
    • +
  • GroupingText property for fieldset/legend rendering
    • +
  • Direction property for text direction (LTR/RTL)
    • +
  • HorizontalAlign property for text alignment
    • +
  • ScrollBars property for overflow control
    • +
  • Wrap property for content wrapping
    • +
  • BackImageUrl property for background images
    • +
  • All style properties (BackColor, ForeColor, CssClass, etc.)
    • +
  • Visible property to show/hide the panel
    • +
+

Web Forms Features NOT Supported

+
    +
  • DefaultButton - JavaScript-based button targeting is not implemented
    • +
+

Syntax Comparison

+
+
+
+
<asp:Panel
+    ID="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    DefaultButton="string"
+    Direction="NotSet|LeftToRight|RightToLeft"
+    Enabled="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Size="string"
+    ForeColor="color name|#dddddd"
+    GroupingText="string"
+    Height="size"
+    HorizontalAlign="NotSet|Left|Center|Right|Justify"
+    ScrollBars="None|Horizontal|Vertical|Both|Auto"
+    Visible="True|False"
+    Width="size"
+    Wrap="True|False"
+    runat="server">
+
+    <!-- Child content here -->
+
+</asp:Panel>
+
+
+
+
<Panel>
+    <p>This is content inside a panel.</p>
+</Panel>
+
+
+
+
+

Blazor Syntax

+

Basic Panel

+
<Panel>
+    <p>This is content inside a panel.</p>
+</Panel>
+
+

Panel with CSS Class

+
<Panel CssClass="card p-3">
+    <h3>Card Title</h3>
+    <p>Card content goes here.</p>
+</Panel>
+
+

Panel with GroupingText (Fieldset)

+

When GroupingText is set, the Panel renders as a <fieldset> with a <legend>:

+
<Panel GroupingText="Personal Information">
+    <Label Text="Name:" />
+    <TextBox @bind-Text="name" />
+    <br />
+    <Label Text="Email:" />
+    <TextBox @bind-Text="email" TextMode="TextBoxMode.Email" />
+</Panel>
+
+

Renders as: +

<fieldset>
+    <legend>Personal Information</legend>
+    <!-- content -->
+</fieldset>
+

+

Panel with ScrollBars

+
<Panel ScrollBars="ScrollBars.Auto" Height="Unit.Pixel(200)" Width="Unit.Pixel(300)">
+    <p>This content can scroll if it overflows the panel dimensions.</p>
+    <!-- lots of content -->
+</Panel>
+
+

Panel with Text Direction (RTL)

+
<Panel Direction="ContentDirection.RightToLeft">
+    <p>This text will be right-to-left.</p>
+</Panel>
+
+

Panel with Horizontal Alignment

+
<Panel HorizontalAlign="HorizontalAlign.Center">
+    <p>This content is centered.</p>
+</Panel>
+
+

Panel with No Wrap

+
<Panel Wrap="false">
+    <p>This content will not wrap to a new line.</p>
+</Panel>
+
+

Styled Panel

+
@using static BlazorWebFormsComponents.WebColor
+
+<Panel BackColor="LightGray" 
+       ForeColor="DarkBlue"
+       BorderColor="Navy"
+       BorderWidth="Unit.Pixel(1)"
+       BorderStyle="BorderStyle.Solid">
+    <p>Styled panel content.</p>
+</Panel>
+
+

Conditionally Visible Panel

+
<CheckBox Text="Show Details" @bind-Checked="showDetails" />
+
+<Panel Visible="@showDetails">
+    <p>These are the details that can be shown or hidden.</p>
+</Panel>
+
+@code {
+    private bool showDetails = false;
+}
+
+

Panel with BackImageUrl

+

The BackImageUrl property sets a CSS background image on the panel. This renders as an inline background-image:url(...) style.

+
<Panel BackImageUrl="https://example.com/images/background.png"
+       Width="Unit.Pixel(500)"
+       Height="Unit.Pixel(200)"
+       BorderStyle="BorderStyle.Solid"
+       BorderWidth="Unit.Pixel(1)">
+    <p>Content displayed over the background image.</p>
+</Panel>
+
+

Renders as: +

<div style="background-image:url(https://example.com/images/background.png);width:500px;height:200px;border-style:Solid;border-width:1px;">
+    <p>Content displayed over the background image.</p>
+</div>
+

+

HTML Output

+

Default Panel (div)

+

Blazor: +

<Panel CssClass="my-panel">
+    <p>Content</p>
+</Panel>
+

+

Rendered HTML: +

<div class="my-panel">
+    <p>Content</p>
+</div>
+

+

Panel with GroupingText (fieldset)

+

Blazor: +

<Panel GroupingText="Settings" CssClass="settings-group">
+    <p>Content</p>
+</Panel>
+

+

Rendered HTML: +

<fieldset class="settings-group">
+    <legend>Settings</legend>
+    <p>Content</p>
+</fieldset>
+

+

ScrollBars Property Values

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueCSS Output
ScrollBars.NoneNo overflow style
ScrollBars.Horizontaloverflow-x:scroll; overflow-y:hidden
ScrollBars.Verticaloverflow-x:hidden; overflow-y:scroll
ScrollBars.Bothoverflow:scroll
ScrollBars.Autooverflow:auto
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove the asp: prefix and runat="server" attribute
    2. +
  2. Replace ID with @ref if you need a component reference
    3. +
  3. The DefaultButton property is not implemented - use JavaScript or Blazor event handling instead
    4. +
  4. Use ChildContent pattern (content between tags) for child controls
    5. +
+

Before (Web Forms):

+
<asp:Panel ID="pnlDetails" 
+           CssClass="details-panel" 
+           Visible="true" 
+           runat="server">
+    <p>Panel content</p>
+</asp:Panel>
+
+

After (Blazor):

+
<Panel CssClass="details-panel" Visible="true">
+    <p>Panel content</p>
+</Panel>
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/PlaceHolder/index.html b/site/EditorControls/PlaceHolder/index.html new file mode 100644 index 000000000..4288210c5 --- /dev/null +++ b/site/EditorControls/PlaceHolder/index.html @@ -0,0 +1,4750 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + PlaceHolder - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

PlaceHolder

+ +

The PlaceHolder component is meant to emulate the asp:PlaceHolder control in markup and is defined in https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.placeholder?view=netframework-4.8

+

PlaceHolder is a simple container that renders NO wrapper element - it only renders its child content. This is useful for conditionally showing/hiding blocks of content.

+

Blazor Features Supported

+
    +
  • ChildContent - the content to render inside the PlaceHolder
    • +
  • Visible - controls whether the content is rendered
    • +
+

Key Characteristic

+

Unlike Panel, PlaceHolder renders only its children with no wrapper element. This makes it ideal for:

+
    +
  • Conditional rendering of content blocks
    • +
  • Grouping content without affecting HTML structure
    • +
  • Dynamic content placeholders
    • +
+

Usage Examples

+

Basic Usage

+
<PlaceHolder>
+    <p>This content renders directly with no wrapper</p>
+</PlaceHolder>
+
+

Renders as: +

<p>This content renders directly with no wrapper</p>
+

+

Conditional Visibility

+
<PlaceHolder Visible="@showContent">
+    <div>Only shown when showContent is true</div>
+</PlaceHolder>
+
+

Syntax Comparison

+
+
+
+
<asp:PlaceHolder
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    SkinID="string"
+    Visible="True|False"
+/>
+
+
+
+
<!-- Basic usage: renders children with no wrapper element -->
+<PlaceHolder>
+    <h2>Welcome</h2>
+    <p>This content renders directly into the page.</p>
+</PlaceHolder>
+
+<!-- Conditional visibility -->
+<PlaceHolder Visible="@isLoggedIn">
+    <p>Hello, @username! You have @messageCount new messages.</p>
+    <button @onclick="ViewMessages">View Messages</button>
+</PlaceHolder>
+
+@code {
+    private bool isLoggedIn = true;
+    private string username = "Alice";
+    private int messageCount = 3;
+
+    private void ViewMessages() { /* ... */ }
+}
+
+
+
+
+

Migration Notes

+

See Also

+
    +
  • Panel — Div-based container control
    • +
  • MultiView — Multi-view container
    • +
  • View — Individual view within a MultiView
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/RadioButton/index.html b/site/EditorControls/RadioButton/index.html new file mode 100644 index 000000000..a152ac88f --- /dev/null +++ b/site/EditorControls/RadioButton/index.html @@ -0,0 +1,4884 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + RadioButton - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

RadioButton

+

The RadioButton component emulates the ASP.NET Web Forms RadioButton control, allowing users to select one option from a group of mutually exclusive choices. Radio buttons with the same GroupName are automatically grouped together, enabling browser-native mutual exclusion.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.radiobutton?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • Text - Label text displayed next to the radio button
    • +
  • GroupName - Groups radio buttons for mutual exclusion (maps to HTML name attribute)
    • +
  • Checked - Boolean state of the radio button
    • +
  • TextAlign - Position of label (Left or Right)
    • +
  • Enabled - Enables or disables the radio button
    • +
  • CheckedChanged - Event callback for two-way binding
    • +
  • OnCheckedChanged - Web Forms compatible event handler
    • +
  • All style properties (BackColor, ForeColor, CssClass, etc.)
    • +
+

Web Forms Features NOT Supported

+
    +
  • AutoPostBack - Not needed in Blazor. Use the OnCheckedChanged event instead.
    • +
  • GroupName with client-side validation - Use Blazor's validation components instead.
    • +
+

Syntax Comparison

+
+
+
+
<asp:RadioButton 
+    ID="string"
+    Text="string"
+    GroupName="string"
+    Checked="True|False"
+    TextAlign="Left|Right"
+    Enabled="True|False"
+    AutoPostBack="True|False"
+    OnCheckedChanged="CheckedChanged event handler"
+    BackColor="color name|#dddddd"
+    ForeColor="color name|#dddddd"
+    CssClass="string"
+    runat="server" 
+/>
+
+
+
+
<!-- Simple radio button -->
+<RadioButton Text="Option A" />
+
+<!-- Grouped radio buttons (mutually exclusive) -->
+<RadioButton Text="Small" GroupName="Size" Checked="@(size == "Small")" 
+             OnCheckedChanged="@(() => size = "Small")" />
+<RadioButton Text="Medium" GroupName="Size" Checked="@(size == "Medium")" 
+             OnCheckedChanged="@(() => size = "Medium")" />
+<RadioButton Text="Large" GroupName="Size" Checked="@(size == "Large")" 
+             OnCheckedChanged="@(() => size = "Large")" />
+
+<!-- Text alignment -->
+<RadioButton Text="Label on left" TextAlign="Enums.TextAlign.Left" GroupName="Align" />
+<RadioButton Text="Label on right" TextAlign="Enums.TextAlign.Right" GroupName="Align" />
+
+<!-- Two-way binding -->
+<RadioButton Text="Subscribe" Checked="@isSubscribed" 
+             CheckedChanged="@((value) => isSubscribed = value)" />
+
+<!-- Disabled radio button -->
+<RadioButton Text="Cannot select" Enabled="false" />
+
+<!-- Styled radio button -->
+<RadioButton Text="Styled" CssClass="custom-radio" BackColor="LightBlue" GroupName="Styled" />
+
+<!-- Radio button without text (no span wrapper) -->
+<RadioButton GroupName="NoLabel" />
+
+
+
+
+

Key Behaviors

+

GroupName and Mutual Exclusion

+

Radio buttons with the same GroupName share the same HTML name attribute, which enables browser-native mutual exclusion. When one radio button in a group is selected, all others in the same group are automatically deselected.

+
<!-- These three radio buttons are mutually exclusive -->
+<RadioButton Text="Option 1" GroupName="Options" />
+<RadioButton Text="Option 2" GroupName="Options" />
+<RadioButton Text="Option 3" GroupName="Options" />
+
+

HTML Output

+

With Text (TextAlign=Right, default): +

<span class="custom-class">
+    <input id="guid" type="radio" name="GroupName" checked />
+    <label for="guid">Option A</label>
+</span>
+

+

With Text (TextAlign=Left): +

<span>
+    <label for="guid">Option A</label>
+    <input id="guid" type="radio" name="GroupName" />
+</span>
+

+

Without Text: +

<input id="guid" type="radio" name="GroupName" />
+

+

Migration Tips

+
    +
  1. Remove asp: prefix and runat="server": Change <asp:RadioButton runat="server" /> to <RadioButton />
    2. +
  2. Update GroupName usage: The property works the same way in Blazor
    3. +
  3. Replace AutoPostBack: Use OnCheckedChanged event handler instead
    4. +
  4. Two-way binding: Use CheckedChanged callback for @bind-like behavior
    5. +
  5. Update TextAlign: Change TextAlign="Left" to TextAlign="Enums.TextAlign.Left"
    6. +
+

Example Migration

+

Before (Web Forms)

+
<asp:RadioButton ID="rbSmall" Text="Small" GroupName="Size" 
+                 AutoPostBack="true" OnCheckedChanged="Size_Changed" runat="server" />
+<asp:RadioButton ID="rbMedium" Text="Medium" GroupName="Size" 
+                 AutoPostBack="true" OnCheckedChanged="Size_Changed" runat="server" />
+<asp:RadioButton ID="rbLarge" Text="Large" GroupName="Size" 
+                 AutoPostBack="true" OnCheckedChanged="Size_Changed" runat="server" />
+
+

After (Blazor)

+
<RadioButton Text="Small" GroupName="Size" Checked="@(selectedSize == "Small")" 
+             OnCheckedChanged="@(() => selectedSize = "Small")" />
+<RadioButton Text="Medium" GroupName="Size" Checked="@(selectedSize == "Medium")" 
+             OnCheckedChanged="@(() => selectedSize = "Medium")" />
+<RadioButton Text="Large" GroupName="Size" Checked="@(selectedSize == "Large")" 
+             OnCheckedChanged="@(() => selectedSize = "Large")" />
+
+@code {
+    private string selectedSize = "Medium";
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/RadioButtonList/index.html b/site/EditorControls/RadioButtonList/index.html new file mode 100644 index 000000000..0ac334a7c --- /dev/null +++ b/site/EditorControls/RadioButtonList/index.html @@ -0,0 +1,5109 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + RadioButtonList - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

RadioButtonList

+

The RadioButtonList component renders a group of radio buttons that allow users to select a single item from a list. This component supports both static items and data-bound scenarios with various layout options.

+

Original Web Forms documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.radiobuttonlist?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Static items via StaticItems parameter with ListItem collection
    • +
  • Data binding via Items parameter with DataTextField and DataValueField
    • +
  • Two-way binding with @bind-SelectedValue
    • +
  • Selected item tracking via SelectedValue and SelectedIndex
    • +
  • OnSelectedIndexChanged event handler
    • +
  • RepeatLayout options: Table, Flow, OrderedList, UnorderedList
    • +
  • RepeatDirection options: Horizontal, Vertical
    • +
  • TextAlign for label positioning (Left or Right)
    • +
  • Disabled state via Enabled parameter
    • +
  • Per-item disabled state via ListItem.Enabled
    • +
  • Style attributes (BackColor, ForeColor, Font, etc.) and CssClass formatting
    • +
  • CellPadding and CellSpacing for table layout
    • +
  • Access to SelectedItem property
    • +
+

WebForms Features Not Supported

+
    +
  • AutoPostBack is not supported in Blazor - use OnSelectedIndexChanged event instead
    • +
  • AppendDataBoundItems is not implemented
    • +
  • DataSourceID is not supported - bind directly to collections via Items parameter
    • +
  • RepeatColumns is not fully implemented
    • +
+

Syntax Comparison

+
+
+
+
<asp:RadioButtonList
+    ID="rbl1"
+    runat="server"
+    RepeatDirection="Vertical|Horizontal"
+    RepeatLayout="Table|Flow|OrderedList|UnorderedList"
+    TextAlign="Left|Right"
+    CellPadding="integer"
+    CellSpacing="integer"
+    CssClass="string"
+    Enabled="True|False"
+    Visible="True|False"
+    SelectedValue="string"
+    SelectedIndex="integer"
+    AutoPostBack="True|False"
+    OnSelectedIndexChanged="SelectedIndexChanged event handler"
+    DataTextField="string"
+    DataValueField="string">
+
+    <asp:ListItem Value="S" Text="Small" />
+    <asp:ListItem Value="M" Text="Medium" Selected="True" />
+    <asp:ListItem Value="L" Text="Large" />
+
+</asp:RadioButtonList>
+
+
+
+
<RadioButtonList TItem="object" StaticItems="items" @bind-SelectedValue="selectedSize" />
+
+@code {
+    private string selectedSize = "M";
+
+    private ListItemCollection items = new()
+    {
+        new ListItem("Small", "S"),
+        new ListItem("Medium", "M"),
+        new ListItem("Large", "L")
+    };
+}
+
+
+
+
+

Rendered HTML (Table layout, Vertical direction): +

<table id="rbl1">
+    <tr>
+        <td><input id="rbl1_0" type="radio" name="rbl1" value="S" /><label for="rbl1_0">Small</label></td>
+    </tr>
+    <tr>
+        <td><input id="rbl1_1" type="radio" name="rbl1" value="M" checked="checked" /><label for="rbl1_1">Medium</label></td>
+    </tr>
+    <tr>
+        <td><input id="rbl1_2" type="radio" name="rbl1" value="L" /><label for="rbl1_2">Large</label></td>
+    </tr>
+</table>
+

+

Data Binding

+
<RadioButtonList TItem="Size"
+                 Items="sizes"
+                 DataTextField="Name"
+                 DataValueField="Code"
+                 @bind-SelectedValue="selectedSizeCode" />
+
+@code {
+    private string selectedSizeCode = "";
+
+    private List<Size> sizes = new()
+    {
+        new Size { Code = "S", Name = "Small" },
+        new Size { Code = "M", Name = "Medium" },
+        new Size { Code = "L", Name = "Large" },
+        new Size { Code = "XL", Name = "Extra Large" }
+    };
+
+    public class Size
+    {
+        public string Code { get; set; }
+        public string Name { get; set; }
+    }
+}
+
+

With Event Handler

+
<RadioButtonList TItem="object"
+                 StaticItems="items"
+                 @bind-SelectedValue="selectedValue"
+                 OnSelectedIndexChanged="HandleSelectionChanged" />
+
+@code {
+    private string selectedValue = "";
+
+    private void HandleSelectionChanged(ChangeEventArgs e)
+    {
+        Console.WriteLine($"Selection changed to: {selectedValue}");
+    }
+}
+
+

Different Layouts

+
@* Flow layout - inline radio buttons *@
+<RadioButtonList TItem="object"
+                 StaticItems="items"
+                 RepeatLayout="RepeatLayout.Flow"
+                 RepeatDirection="RepeatDirection.Horizontal" />
+
+@* Unordered list layout *@
+<RadioButtonList TItem="object"
+                 StaticItems="items"
+                 RepeatLayout="RepeatLayout.UnorderedList" />
+
+@* Ordered list layout *@
+<RadioButtonList TItem="object"
+                 StaticItems="items"
+                 RepeatLayout="RepeatLayout.OrderedList" />
+
+

Label Position

+
@* Label before radio button (left-aligned text) *@
+<RadioButtonList TItem="object"
+                 StaticItems="items"
+                 TextAlign="TextAlign.Left" />
+
+@* Label after radio button (right-aligned text, default) *@
+<RadioButtonList TItem="object"
+                 StaticItems="items"
+                 TextAlign="TextAlign.Right" />
+
+

With Styling

+
<RadioButtonList TItem="object"
+                 StaticItems="items"
+                 CssClass="custom-radio-list"
+                 BackColor="new WebColor(System.Drawing.Color.LightGray)"
+                 CellPadding="5"
+                 CellSpacing="2" />
+
+

Key Differences from Web Forms

+
    +
  1. Type Parameter: Blazor RadioButtonList requires a TItem type parameter for data binding
    2. +
  2. Property Names: Use StaticItems for the item collection (not Items), as Items is reserved for data-bound scenarios
    3. +
  3. Two-way Binding: Use @bind-SelectedValue for automatic two-way binding
    4. +
  4. Events: Use OnSelectedIndexChanged with ChangeEventArgs instead of specialized event args
    5. +
  5. No AutoPostBack: Blazor's event model doesn't require postback; events fire immediately
    6. +
  6. Mutual Exclusion: All radio buttons automatically share the same name attribute for proper mutual exclusion
    7. +
+

Key Difference from CheckBoxList

+

RadioButtonList renders radio buttons with a shared name attribute for mutual exclusion (only one can be selected), while CheckBoxList uses checkboxes with unique names allowing multiple selections:

+
<!-- RadioButtonList - all inputs have same name for mutual exclusion -->
+<input type="radio" name="rbl1" value="S" />
+<input type="radio" name="rbl1" value="M" checked />
+<input type="radio" name="rbl1" value="L" />
+
+<!-- CheckBoxList - each input has unique name -->
+<input type="checkbox" name="cbl1$0" value="1" />
+<input type="checkbox" name="cbl1$1" value="2" />
+<input type="checkbox" name="cbl1$2" value="3" />
+
+

Common Patterns

+

Pre-select an Item

+
<RadioButtonList TItem="object" StaticItems="items" SelectedValue="M" />
+
+

Disabled RadioButtonList

+
<RadioButtonList TItem="object" StaticItems="items" Enabled="false" />
+
+

Disable Individual Items

+
@code {
+    private ListItemCollection items = new()
+    {
+        new ListItem("Available", "1") { Enabled = true },
+        new ListItem("Unavailable", "2") { Enabled = false },
+        new ListItem("Available", "3") { Enabled = true }
+    };
+}
+
+

Get Selected Item Details

+
var radioList = // reference to RadioButtonList component
+var selectedItem = radioList.SelectedItem;
+var text = selectedItem?.Text;
+var value = selectedItem?.Value;
+
+

Migration Tips

+

When migrating from Web Forms:

+
    +
  1. Replace <asp:RadioButtonList> with <RadioButtonList TItem="object">
    2. +
  2. Rename any Items parameter to StaticItems
    3. +
  3. Replace AutoPostBack="true" with OnSelectedIndexChanged event handler
    4. +
  4. Use @bind-SelectedValue instead of manually managing SelectedValue
    5. +
  5. Remove runat="server" attribute
    6. +
  6. Remove <asp:ListItem> tags and define items in code-behind as ListItemCollection
    7. +
  7. Update RepeatLayout and RepeatDirection to use the enum syntax (e.g., RepeatLayout.Table)
    8. +
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/ScriptManager/index.html b/site/EditorControls/ScriptManager/index.html new file mode 100644 index 000000000..7b9806345 --- /dev/null +++ b/site/EditorControls/ScriptManager/index.html @@ -0,0 +1,4906 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ScriptManager - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ScriptManager

+

The ScriptManager component is a migration compatibility stub that renders no output. In Web Forms, ScriptManager was a required page-level component that managed JavaScript libraries, partial-page rendering, and web service proxies. In Blazor, all of these concerns are handled natively by the framework — ScriptManager exists solely to prevent compilation errors during migration.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.scriptmanager?view=netframework-4.8

+
+

Migration Stub Only

+

This component renders nothing to the page. It exists so that migrated Web Forms markup compiles without errors. Once your migration is stable, remove <ScriptManager /> from your pages.

+
+

Features Supported in Blazor

+

The following properties are accepted as parameters for markup compatibility but have no effect:

+
    +
  • EnablePartialRendering — Blazor renders partially by default via its component model
    • +
  • EnablePageMethods — Not applicable; use Blazor component methods directly
    • +
  • ScriptMode — Not applicable; Blazor handles script delivery
    • +
  • AsyncPostBackTimeout — Not applicable; Blazor uses SignalR with its own timeout configuration
    • +
  • EnableCdn — Not applicable; use standard Blazor static asset hosting
    • +
  • EnableScriptGlobalization — Not applicable; use .NET globalization APIs directly
    • +
  • EnableScriptLocalization — Not applicable; use .NET localization APIs directly
    • +
+

Blazor Notes

+
    +
  • ScriptManager is a no-op component — it renders no HTML and performs no actions
    • +
  • All properties are accepted silently to avoid compilation errors during migration
    • +
  • Blazor's built-in features replace every function ScriptManager provided
    • +
+

Web Forms Features NOT Supported

+

Since this is a stub component, all features are effectively unsupported. The properties are accepted but ignored:

+
    +
  • Script registration (RegisterClientScriptBlock, RegisterStartupScript) — Use Blazor's IJSRuntime for JavaScript interop
    • +
  • Web service proxies (ServiceReference) — Use HttpClient or gRPC
    • +
  • Partial rendering coordination — Blazor components re-render automatically
    • +
  • Error handling (AsyncPostBackError) — Use Blazor's ErrorBoundary component
    • +
  • Script combining/bundling — Use standard ASP.NET Core bundling or a build tool
    • +
+

Syntax Comparison

+
+
+
+
<asp:ScriptManager
+    AsyncPostBackErrorMessage="string"
+    AsyncPostBackTimeout="integer"
+    EnableCdn="True|False"
+    EnablePageMethods="True|False"
+    EnablePartialRendering="True|False"
+    EnableScriptGlobalization="True|False"
+    EnableScriptLocalization="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    OnAsyncPostBackError="AsyncPostBackError event handler"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    ScriptMode="Auto|Inherit|Debug|Release"
+    Visible="True|False"
+/>
+
+
+
+
@* Include during migration to prevent compilation errors *@
+<ScriptManager />
+
+
+
+
+

With Properties (All Ignored)

+
@* These properties are accepted but have no effect *@
+<ScriptManager EnablePartialRendering="true"
+               EnablePageMethods="true"
+               ScriptMode="ScriptMode.Release"
+               AsyncPostBackTimeout="90" />
+
+

HTML Output

+

ScriptManager renders no HTML output. It is a silent stub.

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Keep ScriptManager initially — Include <ScriptManager /> in your migrated pages so the markup compiles
    2. +
  2. Remove when stable — Once your page is working in Blazor, delete the <ScriptManager /> tag entirely
    3. +
  3. Replace script registration — Move any ScriptManager.RegisterClientScriptBlock() or RegisterStartupScript() calls to Blazor's IJSRuntime
    4. +
  4. Replace web service calls — Convert PageMethods and ServiceReference calls to HttpClient or direct Blazor service injection
    5. +
+
+

Best Practice

+

Treat ScriptManager as scaffolding. Include it early in migration to keep pages compiling, then remove it as part of your cleanup pass. A page with <ScriptManager /> works identically to one without it.

+
+

Before (Web Forms)

+
<asp:ScriptManager ID="ScriptManager1" runat="server"
+                   EnablePartialRendering="true"
+                   EnablePageMethods="true" />
+
+<asp:UpdatePanel ID="UpdatePanel1" runat="server">
+    <ContentTemplate>
+        <asp:Label ID="lblResult" runat="server" />
+        <asp:Button ID="btnLoad" runat="server"
+                    Text="Load Data"
+                    OnClick="btnLoad_Click" />
+    </ContentTemplate>
+</asp:UpdatePanel>
+
+

After (Blazor)

+
@* ScriptManager can be included during migration but is not needed *@
+<ScriptManager />
+
+<Label Text="@result" />
+<Button Text="Load Data" OnClick="LoadData" />
+
+@code {
+    private string result = "";
+
+    void LoadData()
+    {
+        result = "Data loaded!";
+    }
+}
+
+

After (Blazor — Cleaned Up)

+
@* ScriptManager removed — not needed in Blazor *@
+
+<Label Text="@result" />
+<Button Text="Load Data" OnClick="LoadData" />
+
+@code {
+    private string result = "";
+
+    void LoadData()
+    {
+        result = "Data loaded!";
+    }
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/ScriptManagerProxy/index.html b/site/EditorControls/ScriptManagerProxy/index.html new file mode 100644 index 000000000..e48d80454 --- /dev/null +++ b/site/EditorControls/ScriptManagerProxy/index.html @@ -0,0 +1,4814 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ScriptManagerProxy - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ScriptManagerProxy

+

The ScriptManagerProxy component is a migration compatibility stub that renders no output. In Web Forms, ScriptManagerProxy was used in content pages and user controls to add scripts and services when the main ScriptManager was defined in a master page. In Blazor, this concept does not apply — ScriptManagerProxy exists solely to prevent compilation errors during migration.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.scriptmanagerproxy?view=netframework-4.8

+
+

Migration Stub Only

+

This component renders nothing to the page. It exists so that migrated Web Forms markup compiles without errors. Once your migration is stable, remove <ScriptManagerProxy /> from your pages.

+
+

Features Supported in Blazor

+

No features are actively supported. The component silently accepts its presence in markup for migration compatibility.

+

Blazor Notes

+
    +
  • ScriptManagerProxy is a no-op component — it renders no HTML and performs no actions
    • +
  • In Web Forms, this was needed because only one ScriptManager could exist per page, and content pages used ScriptManagerProxy to register additional scripts. In Blazor, there is no such restriction — use IJSRuntime anywhere.
    • +
+

Web Forms Features NOT Supported

+
    +
  • Script registration (Scripts collection) — Use Blazor's IJSRuntime
    • +
  • Service references (Services collection) — Use dependency injection and HttpClient
    • +
  • AuthenticationService, ProfileService, RoleService — Use ASP.NET Core Identity
    • +
+

Syntax Comparison

+
+
+
+
<asp:ScriptManagerProxy
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    Visible="True|False"
+>
+    <Scripts>
+        <asp:ScriptReference Path="~/Scripts/custom.js" />
+    </Scripts>
+    <Services>
+        <asp:ServiceReference Path="~/WebServices/MyService.asmx" />
+    </Services>
+</asp:ScriptManagerProxy>
+
+
+
+
@* Include during migration to prevent compilation errors *@
+<ScriptManagerProxy />
+
+
+
+
+

HTML Output

+

ScriptManagerProxy renders no HTML output. It is a silent stub.

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Keep ScriptManagerProxy initially — Include <ScriptManagerProxy /> so your migrated content pages compile
    2. +
  2. Remove when stable — Delete <ScriptManagerProxy /> during your cleanup pass
    3. +
  3. Migrate script references — Replace <Scripts> collections with Blazor's IJSRuntime.InvokeAsync or <script> tags in your host page
    4. +
  4. Migrate service references — Replace <Services> collections with dependency-injected services
    5. +
+
+

Best Practice

+

ScriptManagerProxy was a workaround for Web Forms' single-ScriptManager-per-page limitation. Blazor has no such limitation — you can call IJSRuntime from any component. Remove ScriptManagerProxy as soon as your page compiles without it.

+
+

Before (Web Forms — Content Page)

+
<%@ Page Title="Dashboard" MasterPageFile="~/Site.Master" %>
+
+<asp:Content ContentPlaceHolderID="MainContent" runat="server">
+    <asp:ScriptManagerProxy ID="ScriptManagerProxy1" runat="server">
+        <Scripts>
+            <asp:ScriptReference Path="~/Scripts/dashboard.js" />
+        </Scripts>
+    </asp:ScriptManagerProxy>
+
+    <asp:Label ID="lblStatus" runat="server" Text="Loading..." />
+</asp:Content>
+
+

After (Blazor)

+
@inject IJSRuntime JS
+
+@* ScriptManagerProxy included for migration, can be removed *@
+<ScriptManagerProxy />
+
+<Label Text="@status" />
+
+@code {
+    private string status = "Loading...";
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            await JS.InvokeVoidAsync("dashboardInit");
+        }
+    }
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Substitution/index.html b/site/EditorControls/Substitution/index.html new file mode 100644 index 000000000..0c9227d85 --- /dev/null +++ b/site/EditorControls/Substitution/index.html @@ -0,0 +1,4974 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Substitution - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Substitution

+

The Substitution component renders dynamic content by invoking a callback function. In Web Forms, the Substitution control was used for post-cache substitution — injecting dynamic content into output-cached pages. In Blazor, output caching does not apply, so Substitution simply renders the return value of its callback directly.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.substitution?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • SubstitutionCallback — A Func<HttpContext, string> delegate that returns the content to render
    • +
  • MethodName — Accepted for migration reference (string); use SubstitutionCallback for the actual delegate
    • +
+

Blazor Notes

+
    +
  • In Web Forms, the callback was a static method referenced by name (MethodName). In Blazor, you pass a delegate directly via the SubstitutionCallback parameter
    • +
  • The callback receives an HttpContext parameter for compatibility, allowing access to request/user information
    • +
  • The return value of the callback is rendered as raw string content
    • +
  • Post-cache substitution does not apply in Blazor — the component simply invokes the callback on each render
    • +
+

Web Forms Features NOT Supported

+
    +
  • Post-cache substitution — Blazor does not use output caching in the same way; all rendering is dynamic by default
    • +
  • Static method resolution by name — Use the SubstitutionCallback delegate parameter instead of relying on MethodName string resolution
    • +
+

Syntax Comparison

+
+
+
+
<%@ OutputCache Duration="60" VaryByParam="none" %>
+
+<asp:Substitution
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    MethodName="string"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    Visible="True|False"
+/>
+
+
+
+
<Substitution SubstitutionCallback="GetCurrentTime" />
+
+@code {
+    string GetCurrentTime(HttpContext context)
+    {
+        return DateTime.Now.ToString("HH:mm:ss");
+    }
+}
+
+
+
+
+

With MethodName (Migration Reference)

+
@* MethodName kept for documentation; SubstitutionCallback does the work *@
+<Substitution MethodName="GetGreeting"
+              SubstitutionCallback="GetGreeting" />
+
+@code {
+    string GetGreeting(HttpContext context)
+    {
+        var name = context.User.Identity?.Name ?? "Guest";
+        return $"Hello, {name}!";
+    }
+}
+
+

HTML Output

+

Substitution renders the return value of the callback as inline text with no wrapper element.

+

Blazor: +

<Substitution SubstitutionCallback="GetTime" />
+

+

Rendered HTML (example): +

14:30:45
+

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Convert static methods to instance methods — Web Forms required MethodName to point to a public static string Method(HttpContext context). In Blazor, pass a delegate via SubstitutionCallback — it can be an instance method
    2. +
  2. Remove asp: prefix and runat="server" — Standard Blazor migration
    3. +
  3. Remove OutputCache directive — Post-cache substitution is not needed; Blazor renders dynamically by default
    4. +
  4. Replace MethodName with SubstitutionCallback — Pass the actual delegate instead of a string name
    5. +
+
+

Key Difference

+

In Web Forms, Substitution existed to solve a very specific problem: injecting dynamic content into an otherwise cached page. In Blazor, every render is dynamic — there is no output cache to punch holes in. Substitution in Blazor simply calls your function and renders the result, which is equivalent to calling a method in Razor directly (@GetCurrentTime()). The component exists for markup migration compatibility.

+
+

Before (Web Forms)

+
<%@ OutputCache Duration="60" VaryByParam="none" %>
+
+<p>This content is cached for 60 seconds.</p>
+
+<asp:Substitution ID="TimeStamp" runat="server"
+                  MethodName="GetCurrentTime" />
+
+<p>This content is also cached.</p>
+
+
// Must be a public static method
+public static string GetCurrentTime(HttpContext context)
+{
+    return DateTime.Now.ToString("HH:mm:ss");
+}
+
+

After (Blazor)

+
<p>This content renders on every request.</p>
+
+<Substitution SubstitutionCallback="GetCurrentTime" />
+
+<p>This content also renders on every request.</p>
+
+@code {
+    string GetCurrentTime(HttpContext context)
+    {
+        return DateTime.Now.ToString("HH:mm:ss");
+    }
+}
+
+
+

Consider Native Blazor

+

For new Blazor development, you can replace <Substitution> with a simple Razor expression: @DateTime.Now.ToString("HH:mm:ss"). Use the Substitution component only when you want to preserve the original Web Forms markup structure during migration.

+
+

Examples

+

User-Specific Greeting

+
<Substitution SubstitutionCallback="GetUserGreeting" />
+
+@code {
+    string GetUserGreeting(HttpContext context)
+    {
+        var userName = context.User.Identity?.Name ?? "Guest";
+        return $"Welcome back, {userName}!";
+    }
+}
+
+

Dynamic Footer Content

+
<footer>
+    <Substitution SubstitutionCallback="GetFooter" />
+</footer>
+
+@code {
+    string GetFooter(HttpContext context)
+    {
+        return $"© {DateTime.Now.Year} My Application | Server: {Environment.MachineName}";
+    }
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Table/index.html b/site/EditorControls/Table/index.html new file mode 100644 index 000000000..679bf9af5 --- /dev/null +++ b/site/EditorControls/Table/index.html @@ -0,0 +1,5200 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Table - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Table

+

The Table component provides a container for table rows and cells, rendering as an HTML <table> element. It includes related components: TableRow, TableCell, TableHeaderCell, TableHeaderRow, and TableFooterRow.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.table?view=netframework-4.8

+

Features Supported in Blazor

+

Table Component

+
    +
  • Caption - Table caption text
    • +
  • CaptionAlign - Position of caption (Top, Bottom)
    • +
  • CellPadding - Padding within cells in pixels
    • +
  • CellSpacing - Spacing between cells in pixels
    • +
  • GridLines - Display of grid lines (None, Horizontal, Vertical, Both)
    • +
  • HorizontalAlign - Table alignment (Left, Center, Right)
    • +
  • BackImageUrl - Background image for the table
    • +
  • All style properties (CssClass, BackColor, etc.)
    • +
+

TableRow Component

+
    +
  • TableSection - Where the row belongs (TableHeader, TableBody, TableFooter)
    • +
  • HorizontalAlign - Horizontal alignment of row content
    • +
  • VerticalAlign - Vertical alignment of row content
    • +
  • All style properties
    • +
+

TableCell Component

+
    +
  • ColumnSpan - Number of columns the cell spans
    • +
  • RowSpan - Number of rows the cell spans
    • +
  • HorizontalAlign / VerticalAlign - Content alignment
    • +
  • Wrap - Whether content wraps (default: true)
    • +
  • Text - Text content of the cell
    • +
  • AssociatedHeaderCellID - Accessibility association with header
    • +
+

TableHeaderCell Component

+
    +
  • All TableCell properties plus:
    • +
  • Scope - Header scope for accessibility (Row, Column)
    • +
  • AbbreviatedText - Abbreviated header text for accessibility
    • +
+

Specialized Row Components

+
    +
  • TableHeaderRow - Renders in <thead> section
    • +
  • TableFooterRow - Renders in <tfoot> section
    • +
+

Web Forms Features NOT Supported

+
    +
  • Rows collection - Use declarative child content instead
    • +
  • Programmatic row generation - Build rows in Blazor code
    • +
+

Syntax Comparison

+
+
+
+
<asp:Table
+    ID="Table1"
+    Caption="Product List"
+    CaptionAlign="Top"
+    CellPadding="5"
+    CellSpacing="0"
+    GridLines="Both"
+    HorizontalAlign="Center"
+    runat="server">
+    <asp:TableHeaderRow>
+        <asp:TableHeaderCell Scope="Column">Name</asp:TableHeaderCell>
+        <asp:TableHeaderCell Scope="Column">Price</asp:TableHeaderCell>
+    </asp:TableHeaderRow>
+    <asp:TableRow>
+        <asp:TableCell>Widget</asp:TableCell>
+        <asp:TableCell>$10.00</asp:TableCell>
+    </asp:TableRow>
+    <asp:TableFooterRow>
+        <asp:TableCell ColumnSpan="2">Total: $10.00</asp:TableCell>
+    </asp:TableFooterRow>
+</asp:Table>
+
+
+
+
<Table>
+    <TableRow>
+        <TableCell>Cell 1</TableCell>
+        <TableCell>Cell 2</TableCell>
+    </TableRow>
+    <TableRow>
+        <TableCell>Cell 3</TableCell>
+        <TableCell>Cell 4</TableCell>
+    </TableRow>
+</Table>
+
+
+
+
+ +
<Table Caption="Product Inventory" GridLines="GridLines.Both" CellPadding="5">
+    <TableHeaderRow>
+        <TableHeaderCell Scope="TableHeaderScope.Column">Product</TableHeaderCell>
+        <TableHeaderCell Scope="TableHeaderScope.Column">Quantity</TableHeaderCell>
+        <TableHeaderCell Scope="TableHeaderScope.Column">Price</TableHeaderCell>
+    </TableHeaderRow>
+    <TableRow>
+        <TableCell>Widget A</TableCell>
+        <TableCell HorizontalAlign="HorizontalAlign.Right">50</TableCell>
+        <TableCell HorizontalAlign="HorizontalAlign.Right">$25.00</TableCell>
+    </TableRow>
+    <TableRow>
+        <TableCell>Widget B</TableCell>
+        <TableCell HorizontalAlign="HorizontalAlign.Right">30</TableCell>
+        <TableCell HorizontalAlign="HorizontalAlign.Right">$15.00</TableCell>
+    </TableRow>
+    <TableFooterRow>
+        <TableCell ColumnSpan="2">Total</TableCell>
+        <TableCell HorizontalAlign="HorizontalAlign.Right">$1,700.00</TableCell>
+    </TableFooterRow>
+</Table>
+
+

Cell Spanning

+
<Table GridLines="GridLines.Both" CellPadding="10">
+    <TableRow>
+        <TableCell ColumnSpan="2" HorizontalAlign="HorizontalAlign.Center">
+            Header spanning 2 columns
+        </TableCell>
+    </TableRow>
+    <TableRow>
+        <TableCell RowSpan="2">Spans 2 rows</TableCell>
+        <TableCell>Row 1</TableCell>
+    </TableRow>
+    <TableRow>
+        <TableCell>Row 2</TableCell>
+    </TableRow>
+</Table>
+
+

Accessible Table with Scope

+
<Table Caption="Sales Report" GridLines="GridLines.Both">
+    <TableHeaderRow>
+        <TableHeaderCell></TableHeaderCell>
+        <TableHeaderCell Scope="TableHeaderScope.Column">Q1</TableHeaderCell>
+        <TableHeaderCell Scope="TableHeaderScope.Column">Q2</TableHeaderCell>
+    </TableHeaderRow>
+    <TableRow>
+        <TableHeaderCell Scope="TableHeaderScope.Row">North</TableHeaderCell>
+        <TableCell>$100</TableCell>
+        <TableCell>$150</TableCell>
+    </TableRow>
+    <TableRow>
+        <TableHeaderCell Scope="TableHeaderScope.Row">South</TableHeaderCell>
+        <TableCell>$200</TableCell>
+        <TableCell>$175</TableCell>
+    </TableRow>
+</Table>
+
+

Styled Table

+
<Table CssClass="data-table" 
+       CellPadding="8" 
+       CellSpacing="0" 
+       GridLines="GridLines.Horizontal"
+       HorizontalAlign="HorizontalAlign.Center">
+    <TableHeaderRow CssClass="header-row" BackColor="WebColor.LightGray">
+        <TableHeaderCell>Name</TableHeaderCell>
+        <TableHeaderCell>Status</TableHeaderCell>
+    </TableHeaderRow>
+    <TableRow>
+        <TableCell>Item 1</TableCell>
+        <TableCell ForeColor="WebColor.Green">Active</TableCell>
+    </TableRow>
+</Table>
+
+

HTML Output

+

Blazor: +

<Table Caption="Data" CaptionAlign="TableCaptionAlign.Top" GridLines="GridLines.Both" CellPadding="5">
+    <TableHeaderRow>
+        <TableHeaderCell Scope="TableHeaderScope.Column">Header</TableHeaderCell>
+    </TableHeaderRow>
+    <TableRow>
+        <TableCell>Data</TableCell>
+    </TableRow>
+</Table>
+

+

Rendered HTML: +

<table cellpadding="5" border="1" rules="all" style="border-collapse: collapse">
+    <caption style="caption-side: top">Data</caption>
+    <thead>
+        <tr>
+            <th scope="col">Header</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>Data</td>
+        </tr>
+    </tbody>
+</table>
+

+

GridLines Property Values

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ValueHTML Output
GridLines.NoneNo border or rules
GridLines.Horizontalrules="rows"
GridLines.Verticalrules="cols"
GridLines.Bothrules="all" border="1"
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove the asp: prefix and runat="server" attribute
    2. +
  2. Use enum types with full qualification (e.g., GridLines.Both)
    3. +
  3. Replace programmatic row generation with Blazor @foreach loops
    4. +
  4. The component uses standard <thead>, <tbody>, <tfoot> sections
    5. +
+

Before (Web Forms):

+
<asp:Table ID="tblProducts" GridLines="Both" runat="server">
+    <asp:TableRow>
+        <asp:TableCell>Data</asp:TableCell>
+    </asp:TableRow>
+</asp:Table>
+
+

After (Blazor):

+
<Table GridLines="GridLines.Both">
+    <TableRow>
+        <TableCell>Data</TableCell>
+    </TableRow>
+</Table>
+
+

Dynamic Rows

+
<Table GridLines="GridLines.Both">
+    <TableHeaderRow>
+        <TableHeaderCell>Name</TableHeaderCell>
+        <TableHeaderCell>Value</TableHeaderCell>
+    </TableHeaderRow>
+    @foreach (var item in Items)
+    {
+        <TableRow>
+            <TableCell>@item.Name</TableCell>
+            <TableCell>@item.Value</TableCell>
+        </TableRow>
+    }
+</Table>
+
+

See Also

+
    +
  • GridView - Data-bound grid control
    • +
  • DataList - Data-bound repeating control
    • +
  • Panel - Container control
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/TextBox/index.html b/site/EditorControls/TextBox/index.html new file mode 100644 index 000000000..f995695e2 --- /dev/null +++ b/site/EditorControls/TextBox/index.html @@ -0,0 +1,5031 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TextBox - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

TextBox

+

The TextBox component displays a single-line text box, multi-line text area, or specialized HTML5 input control (password, email, number, date, etc.) for user input.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.textbox?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • Single-line text input (<input type="text">)
    • +
  • Multi-line text area (<textarea>)
    • +
  • Password input (<input type="password">)
    • +
  • HTML5 input types (email, number, date, url, tel, etc.)
    • +
  • Two-way data binding with @bind-Text
    • +
  • MaxLength validation
    • +
  • ReadOnly and Enabled/Disabled states
    • +
  • Rows and Columns for sizing
    • +
  • Placeholder text
    • +
  • All style properties (BackColor, ForeColor, BorderColor, CssClass, Width, Height, etc.)
    • +
  • ToolTip - tooltip text displayed on hover (renders as title attribute)
    • +
  • TabIndex support
    • +
+

Web Forms Features NOT Supported

+
    +
  • AutoPostBack - Not needed in Blazor; use event handlers instead
    • +
  • AutoComplete - Handled by browser settings
    • +
  • TextChanged server event - Use @bind-Text or @onchange event in Blazor
    • +
  • Wrap - Use CSS styling instead
    • +
+

Syntax Comparison

+
+
+
+
<asp:TextBox
+    AccessKey="string"
+    AutoCompleteType="None|Disabled|Search|FirstName|LastName|MiddleName|
+        NamePrefix|NameSuffix|FullName|Nickname|Email|HomePhone|WorkPhone|
+        CellPhone|HomeStreetAddress|HomeCity|HomeState|HomeZipCode|
+        HomeCountryRegion|WorkStreetAddress|WorkCity|WorkState|WorkZipCode|
+        WorkCountryRegion|Gender|Birthday|Occupation|BusinessUrl|
+        Company|Department|DisplayName|JobTitle|Notes"
+    AutoPostBack="True|False"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    Columns="integer"
+    CssClass="string"
+    Enabled="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    MaxLength="integer"
+    OnTextChanged="TextChanged event handler"
+    Placeholder="string"
+    ReadOnly="True|False"
+    Rows="integer"
+    runat="server"
+    TabIndex="integer"
+    Text="string"
+    TextMode="SingleLine|MultiLine|Password|Color|Date|DateTime|
+        DateTimeLocal|Email|Month|Number|Range|Search|Phone|Time|Url|Week"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+    Wrap="True|False"
+/>
+
+
+
+
<TextBox Text="Enter your name" CssClass="form-control" />
+
+
+
+
+

Two-Way Data Binding

+
<TextBox @bind-Text="userName" />
+
+@code {
+    private string userName = "John Doe";
+}
+
+

Password Input

+
<TextBox TextMode="TextBoxMode.Password" Placeholder="Enter password" />
+
+

Multi-Line Text Area

+
<TextBox TextMode="TextBoxMode.MultiLine" 
+         Rows="5" 
+         Columns="40" 
+         @bind-Text="comments" />
+
+

HTML5 Input Types

+
<!-- Email -->
+<TextBox TextMode="TextBoxMode.Email" Placeholder="email@example.com" />
+
+<!-- Number -->
+<TextBox TextMode="TextBoxMode.Number" />
+
+<!-- Date -->
+<TextBox TextMode="TextBoxMode.Date" />
+
+<!-- URL -->
+<TextBox TextMode="TextBoxMode.Url" Placeholder="https://example.com" />
+
+<!-- Phone -->
+<TextBox TextMode="TextBoxMode.Phone" Placeholder="(555) 123-4567" />
+
+

ReadOnly and Disabled

+
<TextBox Text="Read only text" ReadOnly="true" />
+<TextBox Text="Disabled text" Enabled="false" />
+
+

With MaxLength Validation

+
<TextBox MaxLength="10" Placeholder="Max 10 characters" />
+
+

Styled TextBox

+
<TextBox Text="Styled input"
+         BackColor="WebColor.LightYellow"
+         ForeColor="WebColor.Navy"
+         BorderColor="WebColor.Blue"
+         BorderWidth="Unit.Pixel(2)"
+         BorderStyle="BorderStyle.Solid"
+         Width="Unit.Pixel(300)" />
+
+

HTML Output

+

Single-Line TextBox

+

Web Forms Input: +

<asp:TextBox ID="txtName" Text="John" CssClass="form-control" runat="server" />
+

+

Rendered HTML: +

<input type="text" value="John" class="form-control" />
+

+

Password TextBox

+

Web Forms Input: +

<asp:TextBox ID="txtPass" TextMode="Password" runat="server" />
+

+

Rendered HTML: +

<input type="password" />
+

+

Multi-Line TextBox

+

Web Forms Input: +

<asp:TextBox ID="txtComments" TextMode="MultiLine" Rows="5" Columns="40" runat="server" />
+

+

Rendered HTML: +

<textarea rows="5" cols="40"></textarea>
+

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove runat="server" - Not needed in Blazor
    2. +
  2. Remove AutoPostBack - Use @bind-Text or event handlers
    3. +
  3. Replace OnTextChanged with @bind-Text - For real-time updates
    4. +
  4. Update TextMode references - Use TextBoxMode. enum prefix (e.g., TextBoxMode.Password)
    5. +
  5. Use HTML5 input types - Take advantage of new types like Email, Number, Date, etc.
    6. +
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/Timer/index.html b/site/EditorControls/Timer/index.html new file mode 100644 index 000000000..3d068d046 --- /dev/null +++ b/site/EditorControls/Timer/index.html @@ -0,0 +1,4983 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Timer - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Timer

+

The Timer component performs asynchronous postbacks at a defined interval. In Web Forms, the Timer control worked with ScriptManager to trigger partial-page updates via async postbacks. In Blazor, this component uses System.Threading.Timer internally to raise tick events at the specified interval — no ScriptManager dependency is needed.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.timer?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • Interval - The number of milliseconds between tick events (default: 60000)
    • +
  • Enabled - Controls whether the timer is actively firing tick events (default: true)
    • +
  • OnTick - Event handler invoked each time the interval elapses
    • +
+

Blazor Notes

+
    +
  • The Timer component uses System.Threading.Timer internally, not JavaScript setInterval
    • +
  • When Enabled is set to false, the timer stops firing; set it back to true to resume
    • +
  • The timer automatically disposes when the component is removed from the render tree
    • +
  • No ScriptManager or UpdatePanel is required — Blazor's component model handles UI updates natively
    • +
+

Web Forms Features NOT Supported

+
    +
  • ScriptManager dependency - Not applicable; Blazor does not use ScriptManager
    • +
  • Async postback triggers - Blazor re-renders components automatically when state changes
    • +
  • EnableViewState - Blazor handles state differently; use component state instead
    • +
  • OnDataBinding, OnDisposed, OnInit, OnLoad, OnPreRender, OnUnload - Use Blazor lifecycle methods instead
    • +
+

Syntax Comparison

+
+
+
+
<asp:ScriptManager ID="ScriptManager1" runat="server" />
+
+<asp:Timer
+    Enabled="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    Interval="integer"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnTick="Tick event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    Visible="True|False"
+/>
+
+
+
+
<Timer Interval="5000" OnTick="HandleTick" />
+
+@code {
+    void HandleTick()
+    {
+        // Called every 5 seconds
+    }
+}
+
+
+
+
+

Timer with Enable/Disable

+
<Timer Interval="3000" Enabled="@isRunning" OnTick="HandleTick" />
+
+<Button Text="@(isRunning ? "Stop" : "Start")" OnClick="ToggleTimer" />
+
+@code {
+    private bool isRunning = true;
+
+    void ToggleTimer()
+    {
+        isRunning = !isRunning;
+    }
+
+    void HandleTick()
+    {
+        // Called every 3 seconds when enabled
+    }
+}
+
+

HTML Output

+

The Timer component renders no visible HTML output. It is a purely behavioral component that fires events at the specified interval.

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove ScriptManager — Timer no longer requires a ScriptManager on the page
    2. +
  2. Remove UpdatePanel wrappers — Blazor handles partial rendering automatically
    3. +
  3. Remove asp: prefix and runat="server" — Standard Blazor migration
    4. +
  4. Update event handler syntax — Change OnTick="Timer1_Tick" to OnTick="HandleTick"
    5. +
  5. Remove ID — Use @ref if you need a component reference
    6. +
+
+

Key Difference

+

In Web Forms, Timer triggers an async postback that refreshes an UpdatePanel region. In Blazor, the OnTick event handler runs server-side and Blazor's SignalR connection automatically pushes UI updates to the browser. The result is the same — periodic UI updates — but the mechanism is fundamentally different and more efficient.

+
+

Before (Web Forms)

+
<asp:ScriptManager ID="ScriptManager1" runat="server" />
+
+<asp:UpdatePanel ID="UpdatePanel1" runat="server">
+    <ContentTemplate>
+        <asp:Label ID="lblTime" runat="server" />
+        <asp:Timer ID="Timer1" runat="server"
+                   Interval="1000"
+                   OnTick="Timer1_Tick" />
+    </ContentTemplate>
+</asp:UpdatePanel>
+
+
protected void Timer1_Tick(object sender, EventArgs e)
+{
+    lblTime.Text = DateTime.Now.ToString("HH:mm:ss");
+}
+
+

After (Blazor)

+
<Label Text="@currentTime" />
+<Timer Interval="1000" OnTick="HandleTick" />
+
+@code {
+    private string currentTime = DateTime.Now.ToString("HH:mm:ss");
+
+    void HandleTick()
+    {
+        currentTime = DateTime.Now.ToString("HH:mm:ss");
+    }
+}
+
+

Examples

+

Auto-Refreshing Dashboard

+
<Timer Interval="10000" OnTick="RefreshData" />
+
+<GridView DataSource="@orders" AutoGenerateColumns="true" />
+
+@code {
+    private List<Order> orders = new();
+
+    protected override void OnInitialized()
+    {
+        orders = OrderService.GetRecentOrders();
+    }
+
+    void RefreshData()
+    {
+        orders = OrderService.GetRecentOrders();
+    }
+}
+
+

Countdown Timer

+
<Label Text="@($"Time remaining: {secondsLeft}s")" />
+<Timer Interval="1000" Enabled="@(secondsLeft > 0)" OnTick="Countdown" />
+
+@code {
+    private int secondsLeft = 30;
+
+    void Countdown()
+    {
+        secondsLeft--;
+    }
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/UpdatePanel/index.html b/site/EditorControls/UpdatePanel/index.html new file mode 100644 index 000000000..a4311b6cd --- /dev/null +++ b/site/EditorControls/UpdatePanel/index.html @@ -0,0 +1,5092 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + UpdatePanel - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

UpdatePanel

+

The UpdatePanel component wraps content in a <div> or <span> element, emulating the Web Forms UpdatePanel that enabled partial-page updates via AJAX postbacks. In Blazor, all rendering is already partial and incremental via SignalR — UpdatePanel serves as a structural wrapper that preserves HTML output for CSS and JavaScript compatibility.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.updatepanel?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • ChildContent — Content rendered inside the wrapper element
    • +
  • UpdateMode — Accepted for migration compatibility (Always, Conditional)
    • +
  • ChildrenAsTriggers — Accepted for migration compatibility
    • +
  • RenderMode — Controls whether the wrapper renders as a <div> (Block) or <span> (Inline)
    • +
+

Blazor Notes

+
    +
  • UpdatePanel renders as a simple wrapper element — <div> by default, or <span> when RenderMode is set to Inline
    • +
  • The UpdateMode and ChildrenAsTriggers properties are accepted but have no behavioral effect — Blazor's component model handles all incremental rendering automatically
    • +
  • Triggers and conditional updates are handled by Blazor's component lifecycle, not by UpdatePanel
    • +
+

Web Forms Features NOT Supported

+
    +
  • Partial postback coordination — Not applicable; Blazor re-renders incrementally by default
    • +
  • Triggers collection (<Triggers>, AsyncPostBackTrigger, PostBackTrigger) — Not applicable; use Blazor event handlers
    • +
  • ContentTemplate as a separate element — Use ChildContent directly between tags
    • +
  • ScriptManager dependency — Not needed; Blazor manages updates natively
    • +
+

Syntax Comparison

+
+
+
+
<asp:ScriptManager ID="ScriptManager1" runat="server" />
+
+<asp:UpdatePanel
+    ChildrenAsTriggers="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    RenderMode="Block|Inline"
+    runat="server"
+    UpdateMode="Always|Conditional"
+    Visible="True|False"
+>
+    <ContentTemplate>
+        <!-- Content here -->
+    </ContentTemplate>
+    <Triggers>
+        <asp:AsyncPostBackTrigger ControlID="btnRefresh" EventName="Click" />
+    </Triggers>
+</asp:UpdatePanel>
+
+
+
+
<UpdatePanel>
+    <p>This content is wrapped in a div.</p>
+</UpdatePanel>
+
+
+
+
+

Inline Render Mode

+
<UpdatePanel RenderMode="UpdatePanelRenderMode.Inline">
+    <span>This content is wrapped in a span.</span>
+</UpdatePanel>
+
+

With Properties (Migration)

+
<UpdatePanel UpdateMode="UpdatePanelUpdateMode.Conditional"
+             ChildrenAsTriggers="true">
+    <Label Text="@message" />
+    <Button Text="Update" OnClick="HandleClick" />
+</UpdatePanel>
+
+@code {
+    private string message = "Click the button to update.";
+
+    void HandleClick()
+    {
+        message = $"Updated at {DateTime.Now:HH:mm:ss}";
+    }
+}
+
+

HTML Output

+

Block Mode (Default)

+

Blazor: +

<UpdatePanel>
+    <p>Content here</p>
+</UpdatePanel>
+

+

Rendered HTML: +

<div>
+    <p>Content here</p>
+</div>
+

+

Inline Mode

+

Blazor: +

<UpdatePanel RenderMode="UpdatePanelRenderMode.Inline">
+    Status: OK
+</UpdatePanel>
+

+

Rendered HTML: +

<span>
+    Status: OK
+</span>
+

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove ScriptManager — UpdatePanel no longer requires a ScriptManager on the page
    2. +
  2. Remove <ContentTemplate> wrapper — Place content directly between <UpdatePanel> tags
    3. +
  3. Remove <Triggers> section — Blazor event handlers replace trigger-based updates
    4. +
  4. Remove asp: prefix and runat="server" — Standard Blazor migration
    5. +
  5. Keep UpdatePanel for HTML structure — If your CSS or JavaScript targets the wrapper <div>/<span>, keeping UpdatePanel preserves that structure
    6. +
+
+

Key Difference

+

In Web Forms, UpdatePanel was essential for AJAX partial-page updates — without it, every server interaction caused a full page reload. In Blazor, every component re-render is already a partial update via SignalR. UpdatePanel in Blazor is purely a structural wrapper that preserves HTML output compatibility.

+
+

Before (Web Forms)

+
<asp:ScriptManager ID="ScriptManager1" runat="server" />
+
+<asp:UpdatePanel ID="UpdatePanel1" runat="server"
+                 UpdateMode="Conditional">
+    <ContentTemplate>
+        <asp:Label ID="lblStatus" runat="server" Text="Ready" />
+        <asp:Button ID="btnRefresh" runat="server"
+                    Text="Refresh"
+                    OnClick="btnRefresh_Click" />
+    </ContentTemplate>
+    <Triggers>
+        <asp:AsyncPostBackTrigger ControlID="btnRefresh"
+                                  EventName="Click" />
+    </Triggers>
+</asp:UpdatePanel>
+
+
protected void btnRefresh_Click(object sender, EventArgs e)
+{
+    lblStatus.Text = $"Refreshed at {DateTime.Now:HH:mm:ss}";
+}
+
+

After (Blazor)

+
<UpdatePanel UpdateMode="UpdatePanelUpdateMode.Conditional">
+    <Label Text="@status" />
+    <Button Text="Refresh" OnClick="HandleRefresh" />
+</UpdatePanel>
+
+@code {
+    private string status = "Ready";
+
+    void HandleRefresh()
+    {
+        status = $"Refreshed at {DateTime.Now:HH:mm:ss}";
+    }
+}
+
+

Examples

+

Multiple Update Regions

+
<UpdatePanel>
+    <h3>Section A</h3>
+    <Label Text="@sectionA" />
+    <Button Text="Update A" OnClick="UpdateA" />
+</UpdatePanel>
+
+<UpdatePanel>
+    <h3>Section B</h3>
+    <Label Text="@sectionB" />
+    <Button Text="Update B" OnClick="UpdateB" />
+</UpdatePanel>
+
+@code {
+    private string sectionA = "Initial A";
+    private string sectionB = "Initial B";
+
+    void UpdateA() => sectionA = $"A updated at {DateTime.Now:HH:mm:ss}";
+    void UpdateB() => sectionB = $"B updated at {DateTime.Now:HH:mm:ss}";
+}
+
+

Inline UpdatePanel in Text

+
<p>
+    The current status is:
+    <UpdatePanel RenderMode="UpdatePanelRenderMode.Inline">
+        <Label Text="@status" />
+    </UpdatePanel>
+</p>
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/UpdateProgress/index.html b/site/EditorControls/UpdateProgress/index.html new file mode 100644 index 000000000..0d42d2684 --- /dev/null +++ b/site/EditorControls/UpdateProgress/index.html @@ -0,0 +1,5047 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + UpdateProgress - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

UpdateProgress

+

The UpdateProgress component displays a loading indicator while an asynchronous operation is in progress. In Web Forms, UpdateProgress was tied to an UpdatePanel and automatically showed/hid based on async postback state. In Blazor, loading states are managed via component state — UpdateProgress provides the familiar markup structure for migration while adapting to Blazor's state-driven rendering model.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.updateprogress?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • ProgressTemplate — Child content rendered as the loading indicator
    • +
  • AssociatedUpdatePanelID — Accepted for migration compatibility (string)
    • +
  • DisplayAfter — Accepted for migration compatibility (int, milliseconds)
    • +
  • DynamicLayout — Controls whether the progress indicator reserves space in the layout when hidden (true = no space reserved, false = space reserved)
    • +
+

Blazor Notes

+
    +
  • In Blazor, you control visibility of UpdateProgress through component state (e.g., a bool IsLoading flag) rather than through automatic association with an UpdatePanel
    • +
  • The AssociatedUpdatePanelID property is accepted but does not automatically detect when an UpdatePanel is updating — use explicit state management instead
    • +
  • When DynamicLayout is true (default), the component uses display:none when hidden; when false, it uses visibility:hidden to reserve layout space
    • +
+

Web Forms Features NOT Supported

+
    +
  • Automatic UpdatePanel association — Does not automatically show/hide based on UpdatePanel async postback state; use Blazor component state instead
    • +
  • ScriptManager integration — Not applicable; Blazor does not use ScriptManager
    • +
+

Syntax Comparison

+
+
+
+
<asp:ScriptManager ID="ScriptManager1" runat="server" />
+
+<asp:UpdatePanel ID="UpdatePanel1" runat="server">
+    <ContentTemplate>
+        <!-- Content here -->
+    </ContentTemplate>
+</asp:UpdatePanel>
+
+<asp:UpdateProgress
+    AssociatedUpdatePanelID="string"
+    DisplayAfter="integer"
+    DynamicLayout="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    Visible="True|False"
+>
+    <ProgressTemplate>
+        <div>Loading, please wait...</div>
+    </ProgressTemplate>
+</asp:UpdateProgress>
+
+
+
+
@if (isLoading)
+{
+    <UpdateProgress>
+        <ProgressTemplate>
+            <div>Loading, please wait...</div>
+        </ProgressTemplate>
+    </UpdateProgress>
+}
+
+@code {
+    private bool isLoading = false;
+}
+
+
+
+
+

With Properties (Migration)

+
@if (isLoading)
+{
+    <UpdateProgress AssociatedUpdatePanelID="UpdatePanel1"
+                    DisplayAfter="500"
+                    DynamicLayout="true">
+        <ProgressTemplate>
+            <div class="loading-spinner">
+                <img src="images/spinner.gif" alt="Loading..." />
+                <span>Processing your request...</span>
+            </div>
+        </ProgressTemplate>
+    </UpdateProgress>
+}
+
+

HTML Output

+

Blazor: +

<UpdateProgress>
+    <ProgressTemplate>
+        <div>Loading...</div>
+    </ProgressTemplate>
+</UpdateProgress>
+

+

Rendered HTML: +

<div>
+    <div>Loading...</div>
+</div>
+

+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Replace automatic show/hide with state — Instead of relying on UpdatePanel association, use a bool flag to control when UpdateProgress is visible
    2. +
  2. Keep <ProgressTemplate> markup — The template content migrates directly
    3. +
  3. Remove asp: prefix and runat="server" — Standard Blazor migration
    4. +
  4. Wrap in @if block — Use conditional rendering to show/hide the progress indicator
    5. +
+
+

Key Difference

+

In Web Forms, UpdateProgress automatically detected when its associated UpdatePanel was performing an async postback and toggled visibility. In Blazor, you control visibility explicitly through component state. This gives you more precise control over when loading indicators appear.

+
+

Before (Web Forms)

+
<asp:ScriptManager ID="ScriptManager1" runat="server" />
+
+<asp:UpdatePanel ID="UpdatePanel1" runat="server">
+    <ContentTemplate>
+        <asp:GridView ID="GridView1" runat="server" />
+        <asp:Button ID="btnLoad" runat="server"
+                    Text="Load Data"
+                    OnClick="btnLoad_Click" />
+    </ContentTemplate>
+</asp:UpdatePanel>
+
+<asp:UpdateProgress ID="UpdateProgress1" runat="server"
+                    AssociatedUpdatePanelID="UpdatePanel1"
+                    DisplayAfter="300">
+    <ProgressTemplate>
+        <div class="loading">Loading data...</div>
+    </ProgressTemplate>
+</asp:UpdateProgress>
+
+
protected void btnLoad_Click(object sender, EventArgs e)
+{
+    System.Threading.Thread.Sleep(2000); // Simulate slow operation
+    GridView1.DataSource = GetData();
+    GridView1.DataBind();
+}
+
+

After (Blazor)

+
<UpdatePanel>
+    @if (!isLoading)
+    {
+        <GridView DataSource="@data" AutoGenerateColumns="true" />
+    }
+    <Button Text="Load Data" OnClick="LoadData" />
+</UpdatePanel>
+
+@if (isLoading)
+{
+    <UpdateProgress AssociatedUpdatePanelID="UpdatePanel1"
+                    DisplayAfter="300">
+        <ProgressTemplate>
+            <div class="loading">Loading data...</div>
+        </ProgressTemplate>
+    </UpdateProgress>
+}
+
+@code {
+    private List<DataItem> data = new();
+    private bool isLoading = false;
+
+    async Task LoadData()
+    {
+        isLoading = true;
+        StateHasChanged();
+
+        data = await DataService.GetDataAsync();
+
+        isLoading = false;
+    }
+}
+
+

Examples

+

Loading Spinner Pattern

+
<Button Text="Fetch Results" OnClick="FetchResults" />
+
+@if (isLoading)
+{
+    <UpdateProgress>
+        <ProgressTemplate>
+            <div class="spinner-border" role="status">
+                <span class="visually-hidden">Loading...</span>
+            </div>
+        </ProgressTemplate>
+    </UpdateProgress>
+}
+else
+{
+    <Label Text="@result" />
+}
+
+@code {
+    private string result = "";
+    private bool isLoading = false;
+
+    async Task FetchResults()
+    {
+        isLoading = true;
+        StateHasChanged();
+
+        result = await SlowService.GetResultAsync();
+
+        isLoading = false;
+    }
+}
+
+

Progress with Custom Styling

+
@if (isLoading)
+{
+    <UpdateProgress DynamicLayout="false">
+        <ProgressTemplate>
+            <div style="text-align:center; padding:20px;">
+                <p>⏳ Please wait while we process your request...</p>
+                <progress />
+            </div>
+        </ProgressTemplate>
+    </UpdateProgress>
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/EditorControls/View/index.html b/site/EditorControls/View/index.html new file mode 100644 index 000000000..d71a15e28 --- /dev/null +++ b/site/EditorControls/View/index.html @@ -0,0 +1,4892 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

View

+

The View component emulates the ASP.NET Web Forms <asp:View> control. A View is a container that holds a group of controls within a MultiView component. Only one View is visible at a time within its parent MultiView.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.view?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • ChildContent — arbitrary child content rendered when this View is active
    • +
  • OnActivate — event callback fired when this View becomes active in the MultiView
    • +
  • OnDeactivate — event callback fired when this View is deactivated
    • +
  • Auto-registration with parent MultiView via cascading parameter
    • +
  • Visible — controlled by parent MultiView's ActiveViewIndex
    • +
+

Web Forms Features NOT Supported

+
    +
  • Command-based navigation (handled by parent MultiView)
    • +
  • EnableTheming / SkinID — theming not supported in Blazor
    • +
+

Syntax Comparison

+
+
+
+
<asp:MultiView ID="MultiView1" ActiveViewIndex="0" runat="server">
+    <asp:View ID="View1" runat="server">
+        <p>Content for View 1</p>
+    </asp:View>
+    <asp:View ID="View2" runat="server">
+        <p>Content for View 2</p>
+    </asp:View>
+</asp:MultiView>
+
+
+
+
<MultiView ActiveViewIndex="@activeIndex" OnActiveViewChanged="ViewChanged">
+    <View>
+        <p>This is View 1</p>
+        <Button Text="Go to View 2" OnClick="() => activeIndex = 1" />
+    </View>
+    <View>
+        <p>This is View 2</p>
+        <Button Text="Go to View 1" OnClick="() => activeIndex = 0" />
+    </View>
+</MultiView>
+
+@code {
+    private int activeIndex = 0;
+
+    private void ViewChanged(EventArgs e)
+    {
+        // Handle view change
+    }
+}
+
+
+
+
+

A View must always be a child of a MultiView component. Only the active View's content is rendered.

+

View with Event Callbacks

+
<MultiView ActiveViewIndex="@activeIndex">
+    <View OnActivate="FirstViewActivated" OnDeactivate="FirstViewDeactivated">
+        <p>First View</p>
+    </View>
+    <View OnActivate="SecondViewActivated" OnDeactivate="SecondViewDeactivated">
+        <p>Second View</p>
+    </View>
+</MultiView>
+
+@code {
+    private int activeIndex = 0;
+
+    private void FirstViewActivated(EventArgs e) => Console.WriteLine("First view activated");
+    private void FirstViewDeactivated(EventArgs e) => Console.WriteLine("First view deactivated");
+    private void SecondViewActivated(EventArgs e) => Console.WriteLine("Second view activated");
+    private void SecondViewDeactivated(EventArgs e) => Console.WriteLine("Second view deactivated");
+}
+
+

HTML Output

+

View renders no wrapper HTML elements. Only the active View's child content is rendered directly.

+

Blazor Input: +

<MultiView ActiveViewIndex="0">
+    <View><p>View 1 Content</p></View>
+    <View><p>View 2 Content</p></View>
+</MultiView>
+

+

Rendered HTML (when View 1 is active): +

<p>View 1 Content</p>
+

+

Rendered HTML (when View 2 is active): +

<p>View 2 Content</p>
+

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDefaultDescription
ChildContentRenderFragmentnullThe content to render when this View is active
OnActivateEventCallbacknullFired when this View becomes the active View in the MultiView
OnDeactivateEventCallbacknullFired when this View is deactivated (another View becomes active)
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove asp: prefix and runat="server" — Change <asp:View> to <View>
    2. +
  2. Bind ActiveViewIndex — Use two-way binding on the parent MultiView's ActiveViewIndex instead of command-based navigation
    3. +
  3. Replace command navigation — Change button command names (NextView, PrevView) to direct index binding
    4. +
  4. Use event callbacks — Replace any View visibility logic with OnActivate and OnDeactivate callbacks
    5. +
+

Before (Web Forms)

+
<asp:MultiView ID="MultiView1" ActiveViewIndex="0" runat="server">
+    <asp:View ID="View1" runat="server">
+        <p>Step 1</p>
+        <asp:Button ID="btn1" CommandName="NextView" Text="Next" runat="server" />
+    </asp:View>
+    <asp:View ID="View2" runat="server">
+        <p>Step 2</p>
+        <asp:Button ID="btn2" CommandName="PrevView" Text="Previous" runat="server" />
+    </asp:View>
+</asp:MultiView>
+
+

After (Blazor)

+
<MultiView ActiveViewIndex="@activeIndex">
+    <View>
+        <p>Step 1</p>
+        <Button Text="Next" OnClick="() => activeIndex = 1" />
+    </View>
+    <View>
+        <p>Step 2</p>
+        <Button Text="Previous" OnClick="() => activeIndex = 0" />
+    </View>
+</MultiView>
+
+@code {
+    private int activeIndex = 0;
+}
+
+

See Also

+
    +
  • MultiView — Parent container for View components
    • +
  • Panel — Div-based container
    • +
  • PlaceHolder — Container with no wrapper element
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/LoginControls/ChangePassword/index.html b/site/LoginControls/ChangePassword/index.html new file mode 100644 index 000000000..81d703624 --- /dev/null +++ b/site/LoginControls/ChangePassword/index.html @@ -0,0 +1,4947 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ChangePassword - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ChangePassword

+

The ChangePassword component emulates the ASP.NET Web Forms asp:ChangePassword control. It provides a complete user interface for changing a user's password, including current password, new password, and confirmation fields with a two-view layout (Change Password view and Success view).

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.changepassword?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Current password, new password, and confirm new password input fields
    • +
  • Configurable labels and error messages for all fields
    • +
  • Two-view state: Change Password view and Success view
    • +
  • DisplayUserName — optionally show a username field
    • +
  • Cancel, Change Password, and Continue buttons with configurable text and type
    • +
  • Navigation via CancelDestinationPageUrl, ContinueDestinationPageUrl, SuccessPageUrl
    • +
  • Create User, Password Recovery, Help Page, and Edit Profile links
    • +
  • InstructionText and PasswordHintText display
    • +
  • Failure text display on error
    • +
  • OnChangingPassword — before password change (cancellable)
    • +
  • OnChangedPassword — after successful password change
    • +
  • OnChangePasswordError — on error
    • +
  • OnCancelButtonClick, OnContinueButtonClick events
    • +
  • Custom templates via ChangePasswordTemplate and SuccessTemplate
    • +
  • Styling through cascading style components (follows Login control pattern)
    • +
  • Table-based layout matching Web Forms HTML output
    • +
  • Orientation property (Vertical or Horizontal layout)
    • +
  • TextLayout property (TextOnLeft or TextOnTop)
    • +
+

Web Forms Features NOT Supported

+
    +
  • MembershipProvider — marked [Obsolete]; use OnChangingPassword event to integrate with ASP.NET Identity
    • +
  • MailDefinition — email sending not supported in Blazor components
    • +
  • OnSendingMail / OnSendMailError events — not applicable
    • +
+
+

Authentication Integration

+

The ChangePassword component does NOT perform password changes directly. You must handle the OnChangingPassword event and use ASP.NET Identity's UserManager<T>.ChangePasswordAsync() or your own authentication service to perform the actual password change.

+
+

Syntax Comparison

+
+
+
+
<asp:ChangePassword
+    ID="ChangePassword1"
+    ChangePasswordTitleText="Change Your Password"
+    SuccessText="Your password has been changed!"
+    DisplayUserName="False"
+    OnChangingPassword="ChangePassword1_ChangingPassword"
+    OnChangedPassword="ChangePassword1_ChangedPassword"
+    runat="server" />
+
+
+
+
<ChangePassword ID="ChangePassword1"
+    ChangePasswordTitleText="Change Your Password"
+    DisplayUserName="false"
+    OnChangingPassword="HandleChangingPassword"
+    OnChangedPassword="HandleChangedPassword" />
+
+@code {
+    private async Task HandleChangingPassword(LoginCancelEventArgs e)
+    {
+        // Call your identity service to change the password
+        // var result = await UserManager.ChangePasswordAsync(user, currentPassword, newPassword);
+        // if (!result.Succeeded) { e.Cancel = true; }
+    }
+
+    private void HandleChangedPassword(EventArgs e)
+    {
+        // Password changed successfully
+    }
+}
+
+
+
+
+

HTML Output

+

The component renders a table-based layout matching the Web Forms ChangePassword control:

+
<table cellspacing="0" cellpadding="1" id="ChangePassword1" style="border-collapse:collapse;">
+  <tbody>
+    <tr>
+      <td>
+        <table cellpadding="0">
+          <tbody>
+            <tr><td align="center" colspan="2">Change Your Password</td></tr>
+            <tr>
+              <td align="right"><label>Password:</label></td>
+              <td><input type="password" /></td>
+            </tr>
+            <tr>
+              <td align="right"><label>New Password:</label></td>
+              <td><input type="password" /></td>
+            </tr>
+            <tr>
+              <td align="right"><label>Confirm New Password:</label></td>
+              <td><input type="password" /></td>
+            </tr>
+            <tr>
+              <td align="right" colspan="2">
+                <input type="submit" value="Change Password" />
+                <input type="button" value="Cancel" />
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:ChangePassword> to <ChangePassword>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Replace MembershipProvider — Handle OnChangingPassword event instead
    4. +
  4. Remove MailDefinition — Handle email notifications in your own service
    5. +
  5. Event handler signatures — OnChangingPassword uses LoginCancelEventArgs (set Cancel = true to abort)
    6. +
+

Before (Web Forms)

+
<asp:ChangePassword ID="cp1"
+    MembershipProvider="SqlMembershipProvider"
+    OnChangedPassword="cp1_ChangedPassword"
+    runat="server" />
+
+

After (Blazor)

+
<ChangePassword ID="cp1"
+    OnChangingPassword="HandleChanging"
+    OnChangedPassword="HandleChanged" />
+
+@code {
+    private async Task HandleChanging(LoginCancelEventArgs e)
+    {
+        // Use UserManager to change password
+    }
+
+    private void HandleChanged(EventArgs e)
+    {
+        // Success handling
+    }
+}
+
+

Orientation and TextLayout

+

The ChangePassword component supports two layout properties that control how the form is arranged, identical to the Login control:

+

Orientation controls whether fields are stacked vertically or arranged side by side:

+ + + + + + + + + + + + + + + + + +
ValueDescription
Orientation.VerticalFields stacked vertically (default)
Orientation.HorizontalFields arranged side by side
+

TextLayout controls label placement relative to input fields:

+ + + + + + + + + + + + + + + + + +
ValueDescription
LoginTextLayout.TextOnLeftLabels appear to the left of inputs (default)
LoginTextLayout.TextOnTopLabels appear above inputs
+
@using BlazorWebFormsComponents.Enums
+
+<ChangePassword
+    ChangePasswordTitleText="Update Password"
+    Orientation="Orientation.Horizontal"
+    TextLayout="LoginTextLayout.TextOnTop"
+    OnChangingPassword="HandleChanging" />
+
+

Migration Example: Layout Properties

+

Before (Web Forms): +

<asp:ChangePassword ID="cp1" runat="server"
+    Orientation="Horizontal"
+    TextLayout="TextOnTop"
+    OnChangingPassword="cp1_ChangingPassword" />
+

+

After (Blazor): +

@using BlazorWebFormsComponents.Enums
+
+<ChangePassword
+    Orientation="Orientation.Horizontal"
+    TextLayout="LoginTextLayout.TextOnTop"
+    OnChangingPassword="HandleChanging" />
+
+@code {
+    private async Task HandleChanging(LoginCancelEventArgs e)
+    {
+        // Perform password change via your identity service
+    }
+}
+

+
+

Migration Tip

+

In Web Forms, Orientation and TextLayout are simple strings ("Horizontal", "TextOnTop"). In Blazor, they require the fully qualified enum values: Orientation.Horizontal and LoginTextLayout.TextOnTop. Add @using BlazorWebFormsComponents.Enums to your page.

+
+

See Also

+
    +
  • Login — Related login control with identical Orientation and TextLayout support
    • +
  • CreateUserWizard — User registration wizard
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/LoginControls/CreateUserWizard/index.html b/site/LoginControls/CreateUserWizard/index.html new file mode 100644 index 000000000..f0c98f651 --- /dev/null +++ b/site/LoginControls/CreateUserWizard/index.html @@ -0,0 +1,4896 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CreateUserWizard - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

CreateUserWizard

+

The CreateUserWizard component emulates the ASP.NET Web Forms asp:CreateUserWizard control. It provides a complete user registration interface with a two-step wizard: a registration form and a success confirmation page.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.createuserwizard?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • User registration form with UserName, Password, Confirm Password, Email fields
    • +
  • Optional Security Question and Answer fields
    • +
  • Two-step wizard: Create User step and Complete step
    • +
  • AutoGeneratePassword — hides password fields when true
    • +
  • RequireEmail — controls email field visibility
    • +
  • DisplaySideBar — optional sidebar with step navigation
    • +
  • DisplayCancelButton — optional cancel button
    • +
  • Configurable labels, error messages, and button text for all fields
    • +
  • OnCreatingUser — before user creation (cancellable via LoginCancelEventArgs)
    • +
  • OnCreatedUser — after successful creation
    • +
  • OnCreateUserError — on error (provides CreateUserErrorEventArgs)
    • +
  • Navigation events: OnCancelButtonClick, OnContinueButtonClick, OnActiveStepChanged
    • +
  • Custom templates: CreateUserStep, CompleteStep, SideBarTemplate, HeaderTemplate
    • +
  • Styling through cascading style components
    • +
  • Table-based layout matching Web Forms HTML output
    • +
+

Web Forms Features NOT Supported

+
    +
  • MembershipProvider — marked [Obsolete]; use OnCreatingUser event to integrate with ASP.NET Identity
    • +
  • MailDefinition — email sending not supported in Blazor components
    • +
  • Custom WizardStep child components (v1 supports only the two built-in steps)
    • +
  • LoginCreatedUser auto-login — the component fires OnCreatedUser; handle login in your callback
    • +
  • DisableCreatedUser — handle in your OnCreatingUser callback
    • +
+
+

Authentication Integration

+

The CreateUserWizard does NOT create users directly. You must handle the OnCreatingUser event and use ASP.NET Identity's UserManager<T>.CreateAsync() or your own registration service to create the user account.

+
+

Syntax Comparison

+
+
+
+
<asp:CreateUserWizard
+    ID="CreateUserWizard1"
+    RequireEmail="True"
+    DisplaySideBar="False"
+    OnCreatedUser="CreateUserWizard1_CreatedUser"
+    runat="server" />
+
+
+
+
<CreateUserWizard ID="CreateUserWizard1"
+    RequireEmail="true"
+    DisplaySideBar="false"
+    OnCreatingUser="HandleCreatingUser"
+    OnCreatedUser="HandleCreatedUser"
+    OnCreateUserError="HandleError" />
+
+@code {
+    private async Task HandleCreatingUser(LoginCancelEventArgs e)
+    {
+        // Use UserManager to create the user
+        // var result = await UserManager.CreateAsync(new AppUser { UserName = ... }, password);
+        // if (!result.Succeeded) { e.Cancel = true; }
+    }
+
+    private void HandleCreatedUser(EventArgs e)
+    {
+        // User created successfully — handle login, redirect, etc.
+    }
+
+    private void HandleError(CreateUserErrorEventArgs e)
+    {
+        // Display error: e.ErrorMessage
+    }
+}
+
+
+
+
+

HTML Output

+

Create User Step

+
<table cellspacing="0" cellpadding="1" id="CreateUserWizard1" style="border-collapse:collapse;">
+  <tbody>
+    <tr>
+      <td>
+        <table cellpadding="0">
+          <tbody>
+            <tr><td align="center" colspan="2">Sign Up for Your New Account</td></tr>
+            <tr>
+              <td align="right"><label>User Name:</label></td>
+              <td><input type="text" /></td>
+            </tr>
+            <tr>
+              <td align="right"><label>Password:</label></td>
+              <td><input type="password" /></td>
+            </tr>
+            <tr>
+              <td align="right"><label>Confirm Password:</label></td>
+              <td><input type="password" /></td>
+            </tr>
+            <tr>
+              <td align="right"><label>E-mail:</label></td>
+              <td><input type="text" /></td>
+            </tr>
+            <tr>
+              <td align="right" colspan="2">
+                <input type="submit" value="Create User" />
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+

Complete Step

+
<table cellspacing="0" cellpadding="1" id="CreateUserWizard1" style="border-collapse:collapse;">
+  <tbody>
+    <tr>
+      <td>
+        <table cellpadding="0">
+          <tbody>
+            <tr><td align="center">Complete</td></tr>
+            <tr><td>Your account has been successfully created.</td></tr>
+            <tr><td align="right"><input type="submit" value="Continue" /></td></tr>
+          </tbody>
+        </table>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:CreateUserWizard> to <CreateUserWizard>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Replace MembershipProvider — Handle OnCreatingUser event with ASP.NET Identity
    4. +
  4. Remove MailDefinition — Handle email in your own service
    5. +
  5. Event handler signatures — OnCreatingUser uses LoginCancelEventArgs; OnCreateUserError uses CreateUserErrorEventArgs
    6. +
+

Before (Web Forms)

+
<asp:CreateUserWizard ID="cuw1"
+    MembershipProvider="SqlMembershipProvider"
+    OnCreatedUser="cuw1_CreatedUser"
+    runat="server" />
+
+

After (Blazor)

+
<CreateUserWizard ID="cuw1"
+    OnCreatingUser="HandleCreating"
+    OnCreatedUser="HandleCreated" />
+
+@code {
+    private async Task HandleCreating(LoginCancelEventArgs e)
+    {
+        // Create user via UserManager
+    }
+
+    private void HandleCreated(EventArgs e)
+    {
+        // Handle success
+    }
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/LoginControls/Login/index.html b/site/LoginControls/Login/index.html new file mode 100644 index 000000000..38a61e6ea --- /dev/null +++ b/site/LoginControls/Login/index.html @@ -0,0 +1,4931 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Login - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Login

+

The Login component provides a complete user interface for logging into a web application, including username and password fields, a remember me checkbox, and configurable login button. Original Web Forms documentation is at: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.login?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Username and Password input fields with labels
    • +
  • Remember Me checkbox (configurable visibility)
    • +
  • Login button with configurable text and type
    • +
  • Required field validation for username and password
    • +
  • Failure text display on authentication failure
    • +
  • Password recovery, help page, and create user links
    • +
  • Instruction text display
    • +
  • OnLoggingIn, OnLoggedIn, OnLoginError, and OnAuthenticate events
    • +
  • DestinationPageUrl for redirect after successful login
    • +
  • VisibleWhenLoggedIn to control visibility for authenticated users
    • +
  • Styling support through cascading style components
    • +
  • Orientation property (Vertical or Horizontal layout)
    • +
  • TextLayout property (TextOnLeft or TextOnTop)
    • +
+

WebForms Features Not Supported

+
    +
  • MembershipProvider - use OnAuthenticate event to implement authentication
    • +
  • FailureAction property
    • +
  • LayoutTemplate
    • +
  • RenderOuterTable property
    • +
+

Syntax Comparison

+
+
+
+
<asp:Login
+    CreateUserIconUrl="uri"
+    CreateUserText="string"
+    CreateUserUrl="uri"
+    DestinationPageUrl="uri"
+    DisplayRememberMe="True|False"
+    FailureText="string"
+    HelpPageIconUrl="uri"
+    HelpPageText="string"
+    HelpPageUrl="uri"
+    ID="string"
+    InstructionText="string"
+    LoginButtonImageUrl="uri"
+    LoginButtonText="string"
+    LoginButtonType="Button|Image|Link"
+    MembershipProvider="string"
+    OnAuthenticate="Authenticate event handler"
+    OnLoggedIn="LoggedIn event handler"
+    OnLoggingIn="LoggingIn event handler"
+    OnLoginError="LoginError event handler"
+    PasswordLabelText="string"
+    PasswordRecoveryIconUrl="uri"
+    PasswordRecoveryText="string"
+    PasswordRecoveryUrl="uri"
+    PasswordRequiredErrorMessage="string"
+    RememberMeSet="True|False"
+    RememberMeText="string"
+    runat="server"
+    TitleText="string"
+    UserName="string"
+    UserNameLabelText="string"
+    UserNameRequiredErrorMessage="string"
+    VisibleWhenLoggedIn="True|False"
+/>
+
+
+
+
<Login TitleText="Sign In"
+       UserNameLabelText="Email:"
+       PasswordLabelText="Password:"
+       LoginButtonText="Sign In"
+       OnAuthenticate="HandleAuthenticate"
+       OnLoggedIn="HandleLoggedIn"
+       DestinationPageUrl="/dashboard">
+    <TitleTextStyle ForeColor="Navy" Font-Bold="true" />
+    <LoginButtonStyle BackColor="Blue" ForeColor="White" />
+</Login>
+
+@code {
+    private void HandleAuthenticate(AuthenticateEventArgs args)
+    {
+        // Implement your authentication logic here
+        args.Authenticated = ValidateCredentials(args);
+    }
+
+    private void HandleLoggedIn(EventArgs args)
+    {
+        // Handle successful login
+    }
+}
+
+
+
+
+

Usage Notes

+

The Login component requires integration with Blazor's AuthenticationStateProvider for authentication state management.

+

Authentication Flow

+
    +
  1. User enters credentials and clicks login button
    2. +
  2. OnLoggingIn event fires (can be cancelled)
    3. +
  3. OnAuthenticate event fires - you must set args.Authenticated = true if credentials are valid
    4. +
  4. If authenticated, OnLoggedIn fires and user is redirected to DestinationPageUrl
    5. +
  5. If not authenticated, OnLoginError fires and FailureText is displayed
    6. +
+

Example with Custom Authentication

+
<Login OnAuthenticate="HandleAuthenticate"
+       OnLoggedIn="HandleLoggedIn"
+       OnLoginError="HandleLoginError"
+       DestinationPageUrl="/home">
+</Login>
+
+@code {
+    private async Task HandleAuthenticate(AuthenticateEventArgs args)
+    {
+        // Your authentication logic
+        var result = await AuthService.ValidateAsync(userName, password);
+        args.Authenticated = result.Success;
+    }
+}
+
+

Styling

+

The Login component supports child style components for customization:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Style ComponentDescription
TitleTextStyleStyles the title text
LabelStyleStyles the username and password labels
TextBoxStyleStyles the input text boxes
CheckBoxStyleStyles the remember me checkbox
LoginButtonStyleStyles the login button
FailureTextStyleStyles the failure message
HyperLinkStyleStyles the help and recovery links
InstructionTextStyleStyles the instruction text
ValidatorTextStyleStyles validation error messages
+

Orientation and TextLayout

+

The Login component supports two layout properties that control how the form is arranged:

+

Orientation controls whether fields are stacked vertically or arranged side by side:

+ + + + + + + + + + + + + + + + + +
ValueDescription
Orientation.VerticalFields stacked vertically (default)
Orientation.HorizontalFields arranged side by side
+

TextLayout controls label placement relative to input fields:

+ + + + + + + + + + + + + + + + + +
ValueDescription
LoginTextLayout.TextOnLeftLabels appear to the left of inputs (default)
LoginTextLayout.TextOnTopLabels appear above inputs
+
@using BlazorWebFormsComponents.Enums
+
+<Login TitleText="Sign In"
+       Orientation="Orientation.Horizontal"
+       TextLayout="LoginTextLayout.TextOnTop"
+       InstructionText="Enter your credentials." />
+
+

Migration Example

+

Before (Web Forms): +

<asp:Login ID="Login1" runat="server"
+    TitleText="Sign In"
+    Orientation="Horizontal"
+    TextLayout="TextOnTop"
+    OnAuthenticate="Login1_Authenticate">
+    <TitleTextStyle ForeColor="Navy" Font-Bold="True" />
+    <LoginButtonStyle BackColor="Blue" ForeColor="White" />
+</asp:Login>
+

+

After (Blazor): +

<Login TitleText="Sign In"
+       Orientation="Orientation.Horizontal"
+       TextLayout="LoginTextLayout.TextOnTop"
+       OnAuthenticate="HandleAuthenticate">
+    <TitleTextStyle ForeColor="Navy" Font-Bold="true" />
+    <LoginButtonStyle BackColor="Blue" ForeColor="White" />
+</Login>
+

+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/LoginControls/LoginName/index.html b/site/LoginControls/LoginName/index.html new file mode 100644 index 000000000..2accd34ee --- /dev/null +++ b/site/LoginControls/LoginName/index.html @@ -0,0 +1,4816 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + LoginName - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

LoginName

+

The LoginName component displays the name of the currently logged-in user. It automatically retrieves the user's identity from the Blazor authentication state. Original Web Forms documentation is at: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.loginname?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Displays authenticated user's name
    • +
  • FormatString for customizing the display format
    • +
  • Standard styling properties (BackColor, ForeColor, CssClass, Font, etc.)
    • +
  • Only renders when user is authenticated
    • +
+

WebForms Features Not Supported

+
    +
  • All core features are supported
    • +
+

Syntax Comparison

+
+
+
+
<asp:LoginName
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    Enabled="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    FormatString="string"
+    Height="size"
+    ID="string"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<LoginName FormatString="Welcome, {0}!" />
+
+
+
+
+

Usage Notes

+

The LoginName component uses Blazor's AuthenticationStateProvider to retrieve the current user's authentication state and display name.

+

Basic Usage

+
<!-- Displays just the username -->
+<LoginName />
+
+<!-- Displays with custom format -->
+<LoginName FormatString="Hello, {0}!" />
+
+<!-- With styling -->
+<LoginName FormatString="Logged in as: {0}"
+           ForeColor="Navy"
+           Font-Bold="true" />
+
+

Format String

+

The FormatString property uses standard .NET string formatting. The {0} placeholder is replaced with the authenticated user's name from Identity.Name.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FormatStringExample Output
{0}john.doe
Welcome, {0}!Welcome, john.doe!
Logged in as: {0}Logged in as: john.doe
User: {0} -User: john.doe -
+

Visibility Behavior

+

The LoginName component only renders content when the user is authenticated. If the user is not logged in, nothing is displayed.

+

Integration with Authentication

+

Ensure your Blazor application has authentication properly configured:

+
<!-- In App.razor -->
+<CascadingAuthenticationState>
+    <Router AppAssembly="@typeof(App).Assembly">
+        <!-- ... -->
+    </Router>
+</CascadingAuthenticationState>
+
+

Example in Navigation

+
<nav>
+    <AuthorizeView>
+        <Authorized>
+            <LoginName FormatString="Welcome, {0}" />
+            <LoginStatus LogoutText="Sign Out" />
+        </Authorized>
+        <NotAuthorized>
+            <a href="/login">Sign In</a>
+        </NotAuthorized>
+    </AuthorizeView>
+</nav>
+
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/LoginControls/LoginStatus/index.html b/site/LoginControls/LoginStatus/index.html new file mode 100644 index 000000000..2b7bf49e2 --- /dev/null +++ b/site/LoginControls/LoginStatus/index.html @@ -0,0 +1,4866 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + LoginStatus - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

LoginStatus

+

The LoginStatus component displays a login or logout link depending on the user's authentication state. When the user is logged out, it shows a login link; when logged in, it shows a logout link. Original Web Forms documentation is at: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.loginstatus?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Automatic display switching based on authentication state
    • +
  • LoginText and LogoutText customization
    • +
  • LoginImageUrl and LogoutImageUrl for image-based links
    • +
  • LogoutAction (Refresh or Redirect)
    • +
  • LogoutPageUrl for redirect after logout
    • +
  • LoginPageUrl for navigation to login page (Blazor enhancement)
    • +
  • OnLoggingOut and OnLoggedOut events
    • +
  • Standard styling properties
    • +
+

WebForms Features Not Supported

+
    +
  • LogoutAction.RedirectToLoginPage - use Redirect with LogoutPageUrl instead
    • +
+

Syntax Comparison

+
+
+
+
<asp:LoginStatus
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    Enabled="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    LoginImageUrl="uri"
+    LoginText="string"
+    LogoutAction="Refresh|Redirect|RedirectToLoginPage"
+    LogoutImageUrl="uri"
+    LogoutPageUrl="uri"
+    LogoutText="string"
+    OnLoggedOut="LoggedOut event handler"
+    OnLoggingOut="LoggingOut event handler"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<LoginStatus LoginText="Sign In"
+             LogoutText="Sign Out"
+             LoginPageUrl="/login"
+             LogoutAction="LogoutAction.Redirect"
+             LogoutPageUrl="/goodbye"
+             OnLoggedOut="HandleLoggedOut" />
+
+
+
+
+

Usage Notes

+

The LoginStatus component uses Blazor's AuthenticationStateProvider to determine the current authentication state.

+

Basic Usage

+
<!-- Simple login/logout toggle -->
+<LoginStatus />
+
+<!-- With custom text -->
+<LoginStatus LoginText="Sign In" LogoutText="Sign Out" />
+
+<!-- With redirect after logout -->
+<LoginStatus LogoutAction="LogoutAction.Redirect"
+             LogoutPageUrl="/logged-out" />
+
+

Logout Actions

+ + + + + + + + + + + + + + + + + +
LogoutActionBehavior
RefreshStays on the current page after logout (default)
RedirectNavigates to LogoutPageUrl after logout
+

Event Handling

+
<LoginStatus OnLoggingOut="HandleLoggingOut"
+             OnLoggedOut="HandleLoggedOut" />
+
+@code {
+    private void HandleLoggingOut(LoginCancelEventArgs args)
+    {
+        // Can cancel logout by setting args.Cancel = true
+        if (HasUnsavedChanges)
+        {
+            args.Cancel = true;
+        }
+    }
+
+    private void HandleLoggedOut(EventArgs args)
+    {
+        // Perform cleanup after logout
+        // Note: Your authentication service should handle the actual sign-out
+    }
+}
+
+ +
<LoginStatus LoginImageUrl="/images/login-icon.png"
+             LogoutImageUrl="/images/logout-icon.png"
+             LoginPageUrl="/account/login" />
+
+

Integration Notes

+

The LoginStatus component triggers the logout events but does not perform the actual authentication sign-out. You must handle the OnLoggedOut event to call your authentication service's sign-out method.

+
<LoginStatus OnLoggedOut="HandleLoggedOut" />
+
+@code {
+    [Inject] private AuthenticationService AuthService { get; set; }
+    [Inject] private NavigationManager Navigation { get; set; }
+
+    private async Task HandleLoggedOut(EventArgs args)
+    {
+        await AuthService.SignOutAsync();
+        Navigation.NavigateTo("/", forceLoad: true);
+    }
+}
+
+

LoginPageUrl Property

+

The LoginPageUrl property is a Blazor enhancement not present in the original Web Forms control. It specifies where to navigate when the login link is clicked.

+
<LoginStatus LoginPageUrl="/account/login"
+             LogoutPageUrl="/account/logout" />
+
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/LoginControls/LoginView/index.html b/site/LoginControls/LoginView/index.html new file mode 100644 index 000000000..80358aaee --- /dev/null +++ b/site/LoginControls/LoginView/index.html @@ -0,0 +1,4876 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + LoginView - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

LoginView

+

The LoginView component displays different content based on the user's authentication state and role membership. It allows you to show different UI to anonymous users, authenticated users, and users in specific roles. Original Web Forms documentation is at: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.loginview?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • AnonymousTemplate for unauthenticated users
    • +
  • LoggedInTemplate for authenticated users
    • +
  • RoleGroups for role-based content display
    • +
  • Automatic template selection based on authentication state
    • +
+

WebForms Features Not Supported

+
    +
  • All core features are supported
    • +
+

Syntax Comparison

+
+
+
+
<asp:LoginView
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ID="string"
+    OnViewChanged="ViewChanged event handler"
+    OnViewChanging="ViewChanging event handler"
+    runat="server"
+    SkinID="string"
+    Visible="True|False">
+    <AnonymousTemplate>
+        <!-- Content for anonymous users -->
+    </AnonymousTemplate>
+    <LoggedInTemplate>
+        <!-- Content for logged-in users -->
+    </LoggedInTemplate>
+    <RoleGroups>
+        <asp:RoleGroup Roles="Admin">
+            <ContentTemplate>
+                <!-- Content for Admin role -->
+            </ContentTemplate>
+        </asp:RoleGroup>
+    </RoleGroups>
+</asp:LoginView>
+
+
+
+
<LoginView>
+    <AnonymousTemplate>
+        <p>Please <a href="/login">sign in</a> to continue.</p>
+    </AnonymousTemplate>
+    <LoggedInTemplate>
+        <p>Welcome! You are logged in.</p>
+    </LoggedInTemplate>
+    <RoleGroups>
+        <RoleGroup Roles="Admin,SuperUser">
+            <p>You have administrator access.</p>
+        </RoleGroup>
+        <RoleGroup Roles="Manager">
+            <p>You have manager access.</p>
+        </RoleGroup>
+    </RoleGroups>
+</LoginView>
+
+
+
+
+

Usage Notes

+

The LoginView component uses Blazor's AuthenticationStateProvider to determine the current user's authentication state and role membership.

+

Template Selection Priority

+

The LoginView selects which template to display using this priority:

+
    +
  1. If user is not authenticated: Display AnonymousTemplate
    2. +
  2. If user is authenticated and matches a RoleGroup: Display that RoleGroup's content
    3. +
  3. If user is authenticated but matches no RoleGroup: Display LoggedInTemplate
    4. +
+

Basic Usage

+
<LoginView>
+    <AnonymousTemplate>
+        <div class="alert alert-info">
+            You are not logged in. <a href="/login">Click here to sign in.</a>
+        </div>
+    </AnonymousTemplate>
+    <LoggedInTemplate>
+        <div class="alert alert-success">
+            Welcome back! <LoginName FormatString="Hello, {0}!" />
+        </div>
+    </LoggedInTemplate>
+</LoginView>
+
+

Role-Based Content

+
<LoginView>
+    <AnonymousTemplate>
+        <p>Please log in to access this content.</p>
+    </AnonymousTemplate>
+    <LoggedInTemplate>
+        <p>Welcome, standard user!</p>
+    </LoggedInTemplate>
+    <RoleGroups>
+        <RoleGroup Roles="Admin">
+            <h2>Administrator Dashboard</h2>
+            <p>You have full system access.</p>
+            <a href="/admin">Go to Admin Panel</a>
+        </RoleGroup>
+        <RoleGroup Roles="Editor,Contributor">
+            <h2>Content Management</h2>
+            <p>You can edit and create content.</p>
+            <a href="/content">Manage Content</a>
+        </RoleGroup>
+    </RoleGroups>
+</LoginView>
+
+

RoleGroup Component

+

The RoleGroup component defines content for users in specific roles:

+ + + + + + + + + + + + + + + + + +
PropertyDescription
RolesComma-separated list of role names
ChildContentThe content to display for users in these roles
+
<RoleGroup Roles="Admin,SuperAdmin">
+    <!-- This content shows for Admin OR SuperAdmin users -->
+    <AdminPanel />
+</RoleGroup>
+
+

Multiple Roles

+

When specifying multiple roles in a RoleGroup, a user only needs to be in one of the roles for the content to display:

+
<RoleGroup Roles="Manager,Director,VP">
+    <!-- Shows if user is Manager OR Director OR VP -->
+    <ManagementDashboard />
+</RoleGroup>
+
+

Integration with Blazor Authorization

+

LoginView works alongside Blazor's built-in AuthorizeView component. Use LoginView when you need Web Forms compatibility or role group functionality:

+
<!-- Blazor native approach -->
+<AuthorizeView>
+    <Authorized>Logged in content</Authorized>
+    <NotAuthorized>Anonymous content</NotAuthorized>
+</AuthorizeView>
+
+<!-- Web Forms compatible approach with role groups -->
+<LoginView>
+    <AnonymousTemplate>Anonymous content</AnonymousTemplate>
+    <LoggedInTemplate>Logged in content</LoggedInTemplate>
+    <RoleGroups>
+        <RoleGroup Roles="Admin">Admin content</RoleGroup>
+    </RoleGroups>
+</LoginView>
+
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/LoginControls/PasswordRecovery/index.html b/site/LoginControls/PasswordRecovery/index.html new file mode 100644 index 000000000..3988d4ff2 --- /dev/null +++ b/site/LoginControls/PasswordRecovery/index.html @@ -0,0 +1,5157 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + PasswordRecovery - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

PasswordRecovery

+

The PasswordRecovery component emulates the ASP.NET Web Forms asp:PasswordRecovery control. It provides a three-step password recovery workflow: username identification, security question verification, and a success confirmation. The component renders table-based forms matching the original Web Forms HTML output.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.passwordrecovery?view=netframework-4.8

+

Blazor Features Supported

+
    +
  • Three-step recovery flow:
      +
    1. UserName step — User enters their username
      2. +
    2. Question step — User answers a security question
      3. +
    3. Success step — Confirmation message displayed
      4. +
    +
    • +
  • Configurable labels and text for each step:
      +
    • UserNameTitleText, UserNameInstructionText, UserNameLabelText, UserNameFailureText
      • +
    • QuestionTitleText, QuestionInstructionText, QuestionLabelText, QuestionFailureText
      • +
    • SuccessText
      • +
    +
    • +
  • SubmitButtonText and SubmitButtonType for the submit button
    • +
  • GeneralFailureText for generic error messages
    • +
  • Help page support: HelpPageUrl, HelpPageText, HelpPageIconUrl
    • +
  • SuccessPageUrl — redirect after successful recovery
    • +
  • Events:
      +
    • OnVerifyingUser — before username validation (cancellable via LoginCancelEventArgs)
      • +
    • OnUserLookupError — after a failed user lookup
      • +
    • OnVerifyingAnswer — before answer validation (cancellable)
      • +
    • OnAnswerLookupError — after a failed answer verification
      • +
    • OnSendingMail — before sending recovery email
      • +
    • OnSendMailError — on mail send failure
      • +
    +
    • +
  • Custom templates: UserNameTemplate, QuestionTemplate, SuccessTemplate
    • +
  • SetQuestion() method — set the security question text from your event handler
    • +
  • SkipToSuccess() method — skip the question step when no security question is configured
    • +
  • Styling through cascading style components:
      +
    • FailureTextStyle, TitleTextStyle, LabelStyle, InstructionTextStyle
      • +
    • TextBoxStyle, SubmitButtonStyle, ValidatorTextStyle, HyperLinkStyle, SuccessTextStyle
      • +
    +
    • +
  • BorderPadding and RenderOuterTable layout properties
    • +
  • Table-based layout matching Web Forms HTML output
    • +
+

Blazor Notes

+
    +
  • The component does NOT perform any password recovery or email sending itself. You must implement the recovery logic in the OnVerifyingUser and OnVerifyingAnswer event handlers.
    • +
  • To set the security question displayed in Step 2, call SetQuestion("Your question text") on the component reference from your OnVerifyingUser handler.
    • +
  • If your application does not use security questions, call SkipToSuccess() from your OnVerifyingUser handler to jump directly to the success step.
    • +
  • Cancel the OnVerifyingUser or OnVerifyingAnswer events (set Cancel = true) to display the corresponding failure text and remain on the current step.
    • +
+

Web Forms Features NOT Supported

+
    +
  • MembershipProvider — marked [Obsolete]; use event handlers to integrate with ASP.NET Identity
    • +
  • MailDefinition — email composition and sending must be handled in your own service
    • +
  • ViewState — not needed; Blazor preserves component state natively
    • +
  • Theming / SkinID — not applicable to Blazor
    • +
+
+

Authentication Integration

+

The PasswordRecovery component does NOT look up users, validate answers, or send emails. You must handle the OnVerifyingUser and OnVerifyingAnswer events and use ASP.NET Identity's UserManager<T> or your own authentication service to perform the actual recovery.

+
+

Syntax Comparison

+
+
+
+
<asp:PasswordRecovery
+    ID="PasswordRecovery1"
+    UserNameTitleText="Forgot Your Password?"
+    UserNameInstructionText="Enter your User Name to receive your password."
+    QuestionTitleText="Identity Confirmation"
+    SuccessText="Your password has been sent to you."
+    SubmitButtonText="Submit"
+    HelpPageUrl="~/Help.aspx"
+    HelpPageText="Need help?"
+    OnVerifyingUser="PasswordRecovery1_VerifyingUser"
+    OnVerifyingAnswer="PasswordRecovery1_VerifyingAnswer"
+    OnSendingMail="PasswordRecovery1_SendingMail"
+    runat="server">
+    <TitleTextStyle BackColor="#336699" ForeColor="White" Font-Bold="True" />
+    <InstructionTextStyle Font-Italic="True" ForeColor="#333333" />
+</asp:PasswordRecovery>
+
+
+
+
<PasswordRecovery @ref="passwordRecovery"
+    ID="PasswordRecovery1"
+    UserNameTitleText="Forgot Your Password?"
+    UserNameInstructionText="Enter your User Name to receive your password."
+    QuestionTitleText="Identity Confirmation"
+    SuccessText="Your password has been sent to you."
+    SubmitButtonText="Submit"
+    HelpPageUrl="/help"
+    HelpPageText="Need help?"
+    OnVerifyingUser="HandleVerifyingUser"
+    OnVerifyingAnswer="HandleVerifyingAnswer"
+    OnSendingMail="HandleSendingMail" />
+
+@code {
+    private PasswordRecovery passwordRecovery;
+
+    private async Task HandleVerifyingUser(LoginCancelEventArgs e)
+    {
+        // Look up the user by passwordRecovery.UserName
+        // var user = await UserManager.FindByNameAsync(passwordRecovery.UserName);
+        // if (user == null) { e.Cancel = true; return; }
+        // passwordRecovery.SetQuestion(user.SecurityQuestion);
+    }
+
+    private async Task HandleVerifyingAnswer(LoginCancelEventArgs e)
+    {
+        // Validate the answer: passwordRecovery.Answer
+        // if (!valid) { e.Cancel = true; return; }
+    }
+
+    private async Task HandleSendingMail(MailMessageEventArgs e)
+    {
+        // Send recovery email via your mail service
+    }
+}
+
+
+
+
+

Blazor Usage Notes

+

Skipping the Question Step

+
<PasswordRecovery @ref="passwordRecovery"
+    OnVerifyingUser="HandleVerifyingUser" />
+
+@code {
+    private PasswordRecovery passwordRecovery;
+
+    private async Task HandleVerifyingUser(LoginCancelEventArgs e)
+    {
+        var user = await UserManager.FindByNameAsync(passwordRecovery.UserName);
+        if (user == null) { e.Cancel = true; return; }
+
+        // No security question — skip directly to success
+        await SendRecoveryEmail(user);
+        await passwordRecovery.SkipToSuccess();
+    }
+}
+
+

With Custom Templates

+
<PasswordRecovery>
+    <UserNameTemplate>
+        <div class="recovery-step">
+            <h3>Find Your Account</h3>
+            <input type="text" @bind="username" placeholder="Enter username" />
+            <button @onclick="LookupUser">Next</button>
+        </div>
+    </UserNameTemplate>
+    <SuccessTemplate>
+        <div class="recovery-success">
+            <h3>Check Your Email</h3>
+            <p>We've sent recovery instructions to your registered email address.</p>
+        </div>
+    </SuccessTemplate>
+</PasswordRecovery>
+
+

HTML Output

+

Step 1: UserName

+
<form>
+  <table cellspacing="0" cellpadding="1" id="PasswordRecovery1" style="border-collapse:collapse;">
+    <tbody>
+      <tr>
+        <td>
+          <table cellpadding="0">
+            <tbody>
+              <tr><td align="center" colspan="2">Forgot Your Password?</td></tr>
+              <tr><td align="center" colspan="2">Enter your User Name to receive your password.</td></tr>
+              <tr>
+                <td align="right"><label for="PasswordRecovery1_UserName">User Name:</label></td>
+                <td><input type="text" id="PasswordRecovery1_UserName" /></td>
+              </tr>
+              <tr>
+                <td align="right" colspan="2">
+                  <input type="submit" value="Submit" id="PasswordRecovery1_SubmitButton" />
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</form>
+
+

Step 2: Question

+
<form>
+  <table cellspacing="0" cellpadding="1" id="PasswordRecovery1" style="border-collapse:collapse;">
+    <tbody>
+      <tr>
+        <td>
+          <table cellpadding="0">
+            <tbody>
+              <tr><td align="center" colspan="2">Identity Confirmation</td></tr>
+              <tr><td align="center" colspan="2">Answer the following question to receive your password.</td></tr>
+              <tr>
+                <td align="right">User Name:</td>
+                <td>jsmith</td>
+              </tr>
+              <tr>
+                <td align="right">Question:</td>
+                <td>What is your pet's name?</td>
+              </tr>
+              <tr>
+                <td align="right"><label for="PasswordRecovery1_Answer">Answer:</label></td>
+                <td><input type="text" id="PasswordRecovery1_Answer" /></td>
+              </tr>
+              <tr>
+                <td align="right" colspan="2">
+                  <input type="submit" value="Submit" id="PasswordRecovery1_SubmitButton" />
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</form>
+
+

Step 3: Success

+
<table cellspacing="0" cellpadding="1" id="PasswordRecovery1" style="border-collapse:collapse;">
+  <tbody>
+    <tr>
+      <td>
+        <table cellpadding="0">
+          <tbody>
+            <tr>
+              <td align="center">Your password has been sent to you.</td>
+            </tr>
+          </tbody>
+        </table>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:PasswordRecovery> to <PasswordRecovery>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Replace MembershipProvider — Handle OnVerifyingUser and OnVerifyingAnswer events with ASP.NET Identity
    4. +
  4. Remove MailDefinition — Handle email sending in your OnSendingMail event handler or service
    5. +
  5. Use @ref — Capture a component reference to call SetQuestion() and SkipToSuccess()
    6. +
  6. Style migration — Replace child style elements (<TitleTextStyle BackColor="...">) with cascading style components or CSS classes
    7. +
  7. Event handler signatures — OnVerifyingUser and OnVerifyingAnswer use LoginCancelEventArgs; OnSendingMail uses MailMessageEventArgs
    8. +
+

Before (Web Forms)

+
<asp:PasswordRecovery ID="pr1"
+    MembershipProvider="SqlMembershipProvider"
+    OnVerifyingUser="pr1_VerifyingUser"
+    OnSendingMail="pr1_SendingMail"
+    runat="server">
+    <TitleTextStyle BackColor="#336699" ForeColor="White" />
+    <MailDefinition From="admin@example.com" Subject="Password Recovery" />
+</asp:PasswordRecovery>
+
+

After (Blazor)

+
<PasswordRecovery @ref="pr1"
+    ID="pr1"
+    OnVerifyingUser="HandleVerifyingUser"
+    OnVerifyingAnswer="HandleVerifyingAnswer"
+    OnSendingMail="HandleSendingMail"
+    TitleTextStyle-CssClass="title-style" />
+
+@code {
+    private PasswordRecovery pr1;
+
+    private async Task HandleVerifyingUser(LoginCancelEventArgs e)
+    {
+        var user = await UserManager.FindByNameAsync(pr1.UserName);
+        if (user == null) { e.Cancel = true; return; }
+        pr1.SetQuestion(user.SecurityQuestion);
+    }
+
+    private async Task HandleVerifyingAnswer(LoginCancelEventArgs e)
+    {
+        // Validate answer via your identity service
+    }
+
+    private async Task HandleSendingMail(MailMessageEventArgs e)
+    {
+        // Send email via your mail service
+    }
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/Analyzers/index.html b/site/Migration/Analyzers/index.html new file mode 100644 index 000000000..2b4de1c0b --- /dev/null +++ b/site/Migration/Analyzers/index.html @@ -0,0 +1,7000 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Roslyn Analyzers - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Roslyn Analyzers for Web Forms Migration

+

The BlazorWebFormsComponents.Analyzers NuGet package includes 8 Roslyn analyzers with automatic code fixes that detect leftover Web Forms patterns in your C# code after migration. They run live in Visual Studio and dotnet build, giving you a guided checklist for cleaning up migrated code-behind.

+
+

When to Use These Analyzers

+

Install the analyzer package after you've run the automated migration script (bwfc-migrate.ps1) and the Copilot skill transforms. The analyzers catch code-behind patterns that markup-level tools can't address — things like ViewState["key"] usage, IsPostBack checks, and Response.Redirect() calls that survived the initial migration.

+
+
+

Installation

+

Add the analyzer package to your Blazor project:

+
dotnet add package BlazorWebFormsComponents.Analyzers
+
+

Or add the reference directly to your .csproj:

+
<PackageReference Include="BlazorWebFormsComponents.Analyzers" Version="*" />
+
+

Once installed, diagnostics appear automatically in Visual Studio's Error List and during dotnet build. Each diagnostic includes a code fix you can apply with Ctrl+. (Quick Actions).

+
+

Analyzer Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Rule IDSeverityNameWhat It Detects
BWFC001⚠️ WarningMissing [Parameter] AttributePublic properties on WebControl subclasses without [Parameter]
BWFC002⚠️ WarningViewState UsageViewState["key"] access patterns
BWFC003⚠️ WarningIsPostBack UsageIsPostBack or Page.IsPostBack checks
BWFC004⚠️ WarningResponse.Redirect UsageResponse.Redirect() calls
BWFC005⚠️ WarningSession State UsageSession["key"] and HttpContext.Current access
BWFC010ℹ️ InfoRequired Attribute MissingBWFC components instantiated without critical properties
BWFC011ℹ️ InfoEvent Handler SignatureMethods with (object sender, EventArgs e) signature
BWFC012⚠️ Warningrunat="server" LeftoverString literals containing runat="server"
BWFC013⚠️ WarningResponse Object UsageResponse.Write(), Response.WriteFile(), Response.Clear(), Response.Flush(), Response.End()
BWFC014⚠️ WarningRequest Object UsageRequest.Form[], Request.Cookies[], Request.Headers[], Request.Files, Request.QueryString[], Request.ServerVariables[]
+
+

BWFC001: Missing [Parameter] Attribute

+

Severity: ⚠️ Warning
+Category: Usage

+

What It Detects

+

Public properties on classes that derive from WebControl or CompositeControl that don't have a [Parameter] attribute. In Blazor, any property that should accept values from markup must be decorated with [Parameter] — otherwise the value is silently ignored.

+

The analyzer skips properties that are inherited from BWFC base classes (like ID, CssClass, Visible, Enabled, etc.) and static properties.

+

Why It Matters

+

In Web Forms, public properties on server controls are automatically available in markup. In Blazor, the [Parameter] attribute is required to wire properties to component markup. Missing this attribute is one of the most common issues after migrating custom controls — the component renders but silently ignores values passed from parent components.

+

Example

+
+
+
+
public class ProductCard : WebControl
+{
+    public string ProductName { get; set; }
+    public decimal Price { get; set; }
+}
+
+
+
+
using Microsoft.AspNetCore.Components;
+
+public class ProductCard : WebControl
+{
+    [Parameter]
+    public string ProductName { get; set; }
+
+    [Parameter]
+    public decimal Price { get; set; }
+}
+
+
+
+
+

Code Fix

+

Adds [Parameter] to the property and inserts using Microsoft.AspNetCore.Components; if not already present.

+
+

BWFC002: ViewState Usage

+

Severity: ⚠️ Warning
+Category: Usage

+

What It Detects

+

ViewState["key"] and this.ViewState["key"] element-access patterns in code-behind. Blazor has no ViewState mechanism — it uses in-memory component state instead.

+

Why It Matters

+

ViewState was the persistence mechanism for Web Forms page lifecycle. In Blazor, components live in memory on the server (Blazor Server) or in the browser (Blazor WebAssembly). State is naturally preserved across re-renders as regular C# fields and properties — no serialization needed. Any leftover ViewState access will either fail at compile time or use the BWFC compatibility shim, which is meant as a stepping stone, not a long-term solution.

+

Example

+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        ViewState["SortDirection"] = "ASC";
+    }
+
+    var direction = (string)ViewState["SortDirection"];
+}
+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        // TODO: Replace ViewState["SortDirection"] with component state
+        // ViewState["SortDirection"] = "ASC";
+    }
+
+    // TODO: Replace ViewState["SortDirection"] with component state
+    // var direction = (string)ViewState["SortDirection"];
+}
+
+
+
+
+

Code Fix

+

Comments out the statement and adds a // TODO prompting you to replace it with a component field or property:

+
private string SortDirection { get; set; } = "ASC";
+
+
+

See Also

+

The ViewState utility documentation explains the BWFC compatibility shim and the recommended path to component state.

+
+
+

BWFC003: IsPostBack Usage

+

Severity: ⚠️ Warning
+Category: Usage

+

What It Detects

+

References to IsPostBack and Page.IsPostBack in code-behind. Blazor does not use the postback model — it uses component lifecycle methods instead.

+

Why It Matters

+

In Web Forms, IsPostBack distinguished between the initial page load and subsequent postbacks. In Blazor, this distinction maps to lifecycle methods:

+ + + + + + + + + + + + + + + + + + + + + +
Web Forms PatternBlazor Equivalent
if (!IsPostBack) (first load)OnInitialized / OnInitializedAsync
if (IsPostBack) (postback)Event handlers (@onclick, @onchange, etc.)
Page_Load (every request)OnParametersSet / OnParametersSetAsync
+

Example

+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        BindGrid();
+    }
+}
+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    // TODO: Replace IsPostBack check with Blazor lifecycle (OnInitialized/OnParametersSet)
+    // if (!IsPostBack)
+    // {
+    //     BindGrid();
+    // }
+}
+
+
+
+
+

Code Fix

+

Comments out the IsPostBack block and adds a // TODO suggesting the appropriate lifecycle method. The recommended migration:

+
protected override void OnInitialized()
+{
+    BindGrid();
+}
+
+
+

BWFC004: Response.Redirect Usage

+

Severity: ⚠️ Warning
+Category: Usage

+

What It Detects

+

Calls to Response.Redirect(), this.Response.Redirect(), and HttpContext.Current.Response.Redirect(). Blazor does not have an HttpResponse object available in components — navigation uses NavigationManager instead.

+

Why It Matters

+

Response.Redirect() works by sending an HTTP 302 response to the browser. Blazor Server communicates over a WebSocket (SignalR) connection, so there's no HTTP response to write to. Blazor WebAssembly runs entirely client-side. In both cases, NavigationManager.NavigateTo() is the correct way to perform navigation.

+

Example

+
+
+
+
protected void btnLogin_Click(object sender, EventArgs e)
+{
+    if (ValidateCredentials())
+    {
+        Response.Redirect("~/Dashboard.aspx");
+    }
+}
+
+
+
+
protected void btnLogin_Click(object sender, EventArgs e)
+{
+    if (ValidateCredentials())
+    {
+        // TODO: Replace Response.Redirect("~/Dashboard.aspx") with NavigationManager.NavigateTo("url")
+        ;
+    }
+}
+
+
+
+
+

Code Fix

+

Replaces the statement with a // TODO comment pointing to NavigationManager.NavigateTo(). The recommended migration:

+
@inject NavigationManager Navigation
+
+// In your method:
+Navigation.NavigateTo("/dashboard");
+
+
+

See Also

+

The Response.Redirect utility documentation explains the BWFC compatibility shim for Response.Redirect.

+
+
+

BWFC005: Session State Usage

+

Severity: ⚠️ Warning
+Category: Usage

+

What It Detects

+

Two patterns:

+
    +
  1. Session element access — Session["key"] and this.Session["key"]
    2. +
  2. HttpContext.Current — Any access to HttpContext.Current, which is not available in Blazor
    3. +
+

Why It Matters

+

Web Forms relies heavily on HttpContext.Current and Session for per-user state. In Blazor Server, there is no HttpContext during SignalR hub invocations (which is most of the component lifecycle). Session state should be replaced with:

+
    +
  • Scoped services — registered with builder.Services.AddScoped<TService>(), these are per-circuit in Blazor Server
    • +
  • ProtectedSessionStorage — for browser session-scoped data that survives page reloads
    • +
  • ProtectedLocalStorage — for data that persists across browser sessions
    • +
+

Example

+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    var userId = Session["UserId"];
+    var context = HttpContext.Current;
+    var userName = context.User.Identity.Name;
+}
+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    // TODO: Replace Session["UserId"] with scoped service or ProtectedSessionStorage
+    ;
+    // TODO: Replace HttpContext.Current with scoped service or ProtectedSessionStorage
+    ;
+    var userName = context.User.Identity.Name;
+}
+
+
+
+
+

Code Fix

+

Replaces the statement with a // TODO comment pointing to scoped services or ProtectedSessionStorage.

+
+

BWFC010: Required Attribute Missing

+

Severity: ℹ️ Info
+Category: Usage

+

What It Detects

+

When well-known BWFC component types are instantiated in code-behind without setting critical properties. Currently tracks:

+ + + + + + + + + + + + + + + + + + + + + +
ComponentRequired Property
GridViewDataSource
HyperLinkNavigateUrl
ImageImageUrl
+

The analyzer checks both object initializer syntax and subsequent property assignments on the same variable.

+

Why It Matters

+

These components won't render correctly without their required properties. When you create a GridView in code-behind without setting DataSource, it renders an empty table. This analyzer is a safety net for migrated code where data binding was previously done declaratively in ASPX markup and might have been missed during migration.

+

Example

+
+
+
+
var grid = new GridView();
+grid.AutoGenerateColumns = true;
+// Missing: grid.DataSource = products;
+
+
+
+
// TODO: Set GridView.DataSource — required for correct rendering
+var grid = new GridView();
+grid.AutoGenerateColumns = true;
+// Missing: grid.DataSource = products;
+
+
+
+
+

Code Fix

+

Adds a // TODO comment above the creation statement reminding you to set the required property.

+
+

BWFC011: Event Handler Signature

+

Severity: ℹ️ Info
+Category: Usage

+

What It Detects

+

Methods in Blazor component classes (those deriving from ComponentBase or BWFC base classes) that have the classic Web Forms event handler signature: (object sender, EventArgs e).

+

Why It Matters

+

In Web Forms, event handlers always followed the (object sender, EventArgs e) pattern because the framework wired them up via delegates. In Blazor, events use EventCallback and EventCallback<T>, which don't pass a sender object. Methods with the old signature won't bind correctly to Blazor's @onclick, @onchange, and other event attributes.

+

Example

+
+
+
+
public class ProductPage : WebControl
+{
+    protected void btnSave_Click(object sender, EventArgs e)
+    {
+        SaveProduct();
+    }
+
+    protected void ddlCategory_SelectedIndexChanged(object sender, EventArgs e)
+    {
+        FilterProducts();
+    }
+}
+
+
+
+
public class ProductPage : WebControl
+{
+    // TODO: Convert to EventCallback pattern — remove sender parameter, change return type if needed
+    protected void btnSave_Click(object sender, EventArgs e)
+    {
+        SaveProduct();
+    }
+
+    // TODO: Convert to EventCallback pattern — remove sender parameter, change return type if needed
+    protected void ddlCategory_SelectedIndexChanged(object sender, EventArgs e)
+    {
+        FilterProducts();
+    }
+}
+
+
+
+
+

Code Fix

+

Adds a // TODO comment above the method. The recommended migration:

+
// Simple click handler — no parameters needed
+private void SaveProduct()
+{
+    // Your existing logic
+}
+
+// If you need event data, use the specific args type
+private void FilterProducts(ChangeEventArgs e)
+{
+    var selectedValue = e.Value?.ToString();
+    // Your existing logic
+}
+
+
+

BWFC012: runat="server" Leftover

+

Severity: ⚠️ Warning
+Category: Usage

+

What It Detects

+

String literals in C# code that contain runat="server" or runat='server' (case-insensitive). This typically occurs in code that dynamically builds HTML markup or in test fixtures that reference ASPX patterns.

+

Why It Matters

+

runat="server" was required on every Web Forms server control to distinguish it from plain HTML. Blazor has no concept of this attribute — all components are inherently server-processed. Leftover runat="server" in string literals is dead code at best and confusing at worst.

+

Example

+
+
+
+
private string GetControlMarkup()
+{
+    return "<asp:TextBox ID=\"txtName\" runat=\"server\" />";
+}
+
+
+
+
private string GetControlMarkup()
+{
+    return "<asp:TextBox ID=\"txtName\" />";
+}
+
+
+
+
+

Code Fix

+

Removes the runat="server" substring (and any leading whitespace before it) from the string literal.

+
+

BWFC013: Response Object Usage

+

Severity: ⚠️ Warning
+Category: Usage

+

What It Detects

+

Calls to Response.Write(), Response.WriteFile(), Response.Clear(), Response.Flush(), and Response.End(). Blazor has no HttpResponse object available in components — it uses markup rendering and result objects instead.

+

Why It Matters

+

The Web Forms Response object is tightly coupled to the HTTP request-response cycle. In Blazor Server (which uses SignalR over WebSocket) and Blazor WebAssembly (which runs client-side), there is no HttpResponse to write to. These methods either fail at runtime or require the BWFC compatibility shim, which is meant as a stepping stone, not a long-term solution.

+

Each method maps to a different Blazor pattern:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web Forms MethodBlazor Equivalent
Response.Write()Markup rendering (component state + template)
Response.WriteFile()FileResult (from minimal API) or HttpClient for file downloads
Response.Clear()Not needed — use @if conditionals in markup
Response.Flush()Not needed — streaming is automatic in Blazor Server
Response.End()Early return from event handler + state update
+

Example

+
+
+
+
protected void ExportButton_Click(object sender, EventArgs e)
+{
+    Response.Clear();
+    Response.Write("<html><body>");
+    Response.Write(GenerateReport());
+    Response.Write("</body></html>");
+    Response.End();
+}
+
+
+
+
// TODO: Replace Response.Write/Clear/End with markup rendering or FileResult
+protected void ExportButton_Click(object sender, EventArgs e)
+{
+    // TODO: Replace Response.Write/Clear/End with markup rendering or FileResult
+    // TODO: Replace Response.Write/Clear/End with markup rendering or FileResult
+    // TODO: Replace Response.Write/Clear/End with markup rendering or FileResult
+    // TODO: Replace Response.Write/Clear/End with markup rendering or FileResult
+}
+
+
+
+
+

Code Fix

+

Comments out each Response method call and adds a // TODO comment pointing to the appropriate Blazor pattern.

+ +

For writing HTML content to the page:

+

Instead of Response.Write(), use component state and markup:

+
@page "/report"
+@implements IAsyncDisposable
+
+<div>
+    @if (!string.IsNullOrEmpty(ReportHtml))
+    {
+        @((MarkupString)ReportHtml)
+    }
+</div>
+
+@code {
+    private string ReportHtml { get; set; }
+
+    private void ExportButton_Click()
+    {
+        ReportHtml = GenerateReport();
+    }
+}
+
+

For file downloads:

+

Use a minimal API endpoint that returns FileResult:

+
// In Program.cs or a service:
+app.MapGet("/api/export-report", async () =>
+{
+    var fileBytes = GenerateReportFile();
+    return Results.File(fileBytes, "application/pdf", "report.pdf");
+});
+
+// In your component:
+@inject NavigationManager Navigation
+
+private void ExportButton_Click()
+{
+    Navigation.NavigateTo("/api/export-report", forceLoad: true);
+}
+
+
+

BWFC014: Request Object Usage

+

Severity: ⚠️ Warning
+Category: Usage

+

What It Detects

+

Access to Request.Form[], Request.Cookies[], Request.Headers[], Request.Files, Request.QueryString[], and Request.ServerVariables[]. Blazor does not expose an HttpRequest object in components — data flows through components properties, form binding, and HttpContextAccessor (Blazor Server only).

+

Why It Matters

+

The Web Forms Request object provided a centralized way to access browser-sent data. In Blazor:

+
    +
  • Query strings — Passed as route parameters or via NavigationManager.Uri
    • +
  • Form data — Bound to component properties using @bind
    • +
  • Cookies — Accessed via HttpContextAccessor (Blazor Server only) or JavaScript interop
    • +
  • Headers — Accessed via HttpContextAccessor (Blazor Server only)
    • +
  • Uploaded files — Handled by InputFile component, not raw file access
    • +
+

Leaving Request calls in place will fail at runtime or require compatibility shims.

+

Example

+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    var userId = Request.QueryString["id"];
+    var email = Request.Form["email"];
+    var sessionId = Request.Cookies["session"];
+    var apiKey = Request.Headers["X-API-Key"];
+
+    if (Request.Files.Count > 0)
+    {
+        var file = Request.Files[0];
+    }
+}
+
+
+
+
// TODO: Replace Request.QueryString[] with route parameters or NavigationManager.Uri
+protected void Page_Load(object sender, EventArgs e)
+{
+    // TODO: Replace Request.QueryString[] with route parameters or NavigationManager.Uri
+    // TODO: Replace Request.Form[] with @bind or parameter binding
+    // TODO: Replace Request.Cookies[] with HttpContextAccessor (Blazor Server) or JS interop
+    // TODO: Replace Request.Headers[] with HttpContextAccessor (Blazor Server)
+
+    // TODO: Replace Request.Files with InputFile component
+}
+
+
+
+
+

Code Fix

+

Comments out each Request access and adds a // TODO comment pointing to the appropriate Blazor pattern.

+ +

For query string parameters:

+

Use route parameters in your @page directive:

+
@page "/products/{ProductId:int}"
+
+<h1>Product @ProductId</h1>
+
+@code {
+    [Parameter]
+    public int ProductId { get; set; }
+}
+
+

For form data:

+

Use @bind two-way binding:

+
<input @bind="Email" />
+<button @onclick="HandleSubmit">Submit</button>
+
+@code {
+    private string Email { get; set; }
+
+    private void HandleSubmit()
+    {
+        // Email is already populated
+    }
+}
+
+

For cookies (Blazor Server):

+

Use HttpContextAccessor:

+
@inject HttpContextAccessor HttpContextAccessor
+
+@code {
+    private string GetCookie(string name)
+    {
+        var context = HttpContextAccessor.HttpContext;
+        if (context?.Request.Cookies.TryGetValue(name, out var value) ?? false)
+        {
+            return value;
+        }
+        return null;
+    }
+}
+
+

For headers (Blazor Server):

+

Also use HttpContextAccessor:

+
private string GetHeader(string name)
+{
+    var context = HttpContextAccessor.HttpContext;
+    if (context?.Request.Headers.TryGetValue(name, out var value) ?? false)
+    {
+        return value.ToString();
+    }
+    return null;
+}
+
+

For file uploads:

+

Use the InputFile component:

+
<InputFile OnChange="HandleFileSelected" />
+
+@code {
+    private async Task HandleFileSelected(InputFileChangeEventArgs e)
+    {
+        var file = e.File;
+        using var stream = file.OpenReadStream(maxAllowedSize: 1_000_000);
+        // Process file stream
+    }
+}
+
+
+

See Also

+

The InputFile documentation explains how to use the component for file handling in Blazor.

+
+
+

Using Analyzers in CI/CD

+

The analyzers integrate seamlessly with dotnet build and CI/CD pipelines. You can configure severity levels per rule and fail the build on violations.

+

Example: .editorconfig for CI Enforcement

+
# .editorconfig — enforce analyzer rules in CI
+
+# Mandatory rules: fail the build
+dotnet_diagnostic.BWFC001.severity = error
+dotnet_diagnostic.BWFC003.severity = error
+dotnet_diagnostic.BWFC004.severity = error
+
+# Important patterns: treat as warnings
+dotnet_diagnostic.BWFC002.severity = warning
+dotnet_diagnostic.BWFC005.severity = warning
+dotnet_diagnostic.BWFC011.severity = warning
+dotnet_diagnostic.BWFC012.severity = warning
+dotnet_diagnostic.BWFC013.severity = warning
+dotnet_diagnostic.BWFC014.severity = warning
+
+# Informational patterns: visible but don't block build
+dotnet_diagnostic.BWFC010.severity = suggestion
+
+

CI Workflow

+
# Build the project — BWFC violations will appear as compiler warnings/errors
+dotnet build MyBlazorProject.csproj
+
+# In CI scripts, check for BWFC violations:
+dotnet build MyBlazorProject.csproj --no-restore 2>&1 | grep "BWFC"
+if [ $? -eq 0 ]; then
+    echo "Web Forms migration violations detected"
+    exit 1
+fi
+
+

Notes

+
    +
  • All BWFC diagnostics use the format BWFC{NNN} and can be configured via standard Roslyn mechanisms
    • +
  • Build-time diagnostics are consistent with editor diagnostics
    • +
  • Use .editorconfig to customize severity per project, not per file
    • +
  • For bulk suppression (migrating a large codebase), set all rules to suggestion initially, then upgrade as you clean up
    • +
+
+

Prioritization Guide: Which Rules to Fix First

+

If you're migrating a large application, fix analyzers in this order:

+

Phase 1: Blocking Patterns (Fix First)

+

These patterns prevent your components from working at all:

+
    +
  1. BWFC001 — Missing [Parameter] on public properties
    2. +
  2. Components silently ignore bound values → visual regression
    3. +
  3. +

    Usually quick fixes (add one attribute per property)

    +
    4. +
  4. +

    BWFC003 — IsPostBack checks

    +
    5. +
  5. Affects page initialization and event handling
    6. +
  6. Core logic may depend on this check
    7. +
  7. +

    Need to refactor to OnInitialized / event handlers

    +
    8. +
  8. +

    BWFC004 — Response.Redirect() calls

    +
    9. +
  9. All navigation breaks → user can't move between pages
    10. +
  10. +

    Quick 1:1 replacement with NavigationManager.NavigateTo()

    +
    11. +
  11. +

    BWFC011 — Old event handler signatures

    +
    12. +
  12. Event handlers won't fire → broken interactions
    13. +
  13. Prevents using Blazor's @onclick, @onchange, etc.
    14. +
+

Phase 2: Data & State Patterns (Fix Next)

+

These affect how data flows through your app:

+
    +
  1. BWFC002 — ViewState usage
    2. +
  2. Replace with component fields/properties
    3. +
  3. +

    May require refactoring persistence logic

    +
    4. +
  4. +

    BWFC005 — Session and HttpContext access

    +
    5. +
  5. Replace with scoped services, protected storage, etc.
    6. +
  6. +

    Medium complexity depending on scope

    +
    7. +
  7. +

    BWFC014 — Request object usage

    +
    8. +
  8. Replace with route parameters, @bind, InputFile, etc.
    9. +
  9. Usually straightforward per-instance fixes
    10. +
+

Phase 3: Output & Response Patterns (Fix Last)

+

These are less common and more specialized:

+
    +
  1. BWFC013 — Response.Write(), Response.WriteFile(), etc.
    2. +
  2. Less common in modern applications
    3. +
  3. +

    Usually isolated to reporting/export features

    +
    4. +
  4. +

    BWFC012 — runat="server" in strings

    +
    5. +
  5. Pure string cleanup, no logic impact
    6. +
  6. +

    Can be done last as a polish pass

    +
    7. +
  7. +

    BWFC010 — Missing required attributes

    +
      +
    • Usually caught by testing; low risk
      • +
    • Fix as you discover missing data
      • +
    +
    8. +
+
+

Configuring and Suppressing Rules

+

Using .editorconfig

+

You can adjust severity or disable specific rules using an .editorconfig file in your project:

+
# Disable a specific rule
+dotnet_diagnostic.BWFC001.severity = none
+
+# Downgrade a warning to info
+dotnet_diagnostic.BWFC004.severity = suggestion
+
+# Upgrade an info to warning
+dotnet_diagnostic.BWFC011.severity = warning
+
+

Using Pragma Directives

+

Suppress a diagnostic on a specific line:

+
#pragma warning disable BWFC002
+    var value = ViewState["LegacyKey"];
+#pragma warning restore BWFC002
+
+

Using [SuppressMessage]

+

Suppress at method or class level:

+
[System.Diagnostics.CodeAnalysis.SuppressMessage("Usage", "BWFC005",
+    Justification = "HttpContext.Current is available in this middleware context")]
+public void ConfigureServices()
+{
+    // ...
+}
+
+

Bulk Suppression Strategy

+

If you have a large migrated codebase and want to address analyzers incrementally, consider setting all rules to suggestion initially, then upgrading them to warning as you clean up each category:

+
# Phase 1: See everything as suggestions
+dotnet_diagnostic.BWFC001.severity = suggestion
+dotnet_diagnostic.BWFC002.severity = suggestion
+dotnet_diagnostic.BWFC003.severity = suggestion
+dotnet_diagnostic.BWFC004.severity = suggestion
+dotnet_diagnostic.BWFC005.severity = suggestion
+
+# Phase 2: Enforce rules you've cleaned up
+dotnet_diagnostic.BWFC001.severity = warning
+dotnet_diagnostic.BWFC012.severity = warning
+
+
+ +
    +
  1. Run the automated migration — Use bwfc-migrate.ps1 and the Copilot webforms-migration skill to convert your markup and code-behind
    2. +
  2. Install the analyzer package — Add BlazorWebFormsComponents.Analyzers to your migrated project
    3. +
  3. Build and review — Run dotnet build and review the diagnostics in Visual Studio's Error List
    4. +
  4. Apply code fixes — Use Ctrl+. on each diagnostic to apply the suggested code fix
    5. +
  5. Address TODOs — The code fixes insert // TODO comments that guide your manual refactoring
    6. +
  6. Clean up incrementally — Use .editorconfig to manage which rules are active as you progress through the migration
    7. +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/AutomatedMigration/index.html b/site/Migration/AutomatedMigration/index.html new file mode 100644 index 000000000..3fa04939c --- /dev/null +++ b/site/Migration/AutomatedMigration/index.html @@ -0,0 +1,5229 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Automated Migration Guide - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Automated Migration Guide

+

This guide explains how to use the BlazorWebFormsComponents migration tooling to convert ASP.NET Web Forms applications to Blazor Server with minimal manual effort.

+

Overview

+

The BWFC migration system uses a three-layer pipeline:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LayerToolAutomationWhat It Handles
1. Scannerbwfc-scan.ps1InventoryAnalyzes your Web Forms project and reports migration readiness
2. Scriptbwfc-migrate.ps1~40%Mechanical regex transforms (strip asp:, fix expressions, rename files)
3. Copilot Skillwebforms-migration~45%Structural transforms (code-behind, data binding, lifecycle methods)
4. Agentmigration.agent.md~15%Semantic decisions (Session→DI, Identity, EF Core, architecture)
+
+

Core Principle

+

Strip asp: and runat="server", keep everything else, and it just works. BWFC components match Web Forms control names, property names, and rendered HTML.

+
+

Prerequisites

+
    +
  • .NET 10 SDK or later
    • +
  • PowerShell 7+ (for migration scripts)
    • +
  • GitHub Copilot (for skill and agent layers)
    • +
  • Your Web Forms application source code
    • +
+

Step 1: Scan Your Project

+

Run the scanner to inventory your Web Forms project:

+
pwsh scripts/bwfc-scan.ps1 -Path ./MyWebFormsApp
+
+

The scanner reports:

+
    +
  • All .aspx, .ascx, and .master files found
    • +
  • Every <asp:Control> used and how many times
    • +
  • Which controls have BWFC equivalents (52 supported controls)
    • +
  • Which controls need manual migration (DataSource controls, Wizard, etc.)
    • +
  • An overall migration readiness percentage
    • +
+

Reading the Scan Report

+
=== BWFC Migration Scan Report ===
+
+Files: 12 .aspx, 3 .ascx, 1 .master
+Controls: 47 total across 15 unique types
+
+✅ Supported (96.6%):  Button(8), TextBox(12), Label(6), GridView(2)...
+❌ Not Supported (3.4%): SqlDataSource(2)
+
+Migration Readiness: 96.6%
+
+

Controls marked ❌ need manual replacement with injected services. See Data Binding Migration below.

+

Export Options

+
# JSON for tooling
+pwsh scripts/bwfc-scan.ps1 -Path ./MyWebFormsApp -OutputFormat Json -OutputFile scan.json
+
+# Markdown for documentation
+pwsh scripts/bwfc-scan.ps1 -Path ./MyWebFormsApp -OutputFormat Markdown -OutputFile scan.md
+
+

Step 2: Run Mechanical Transforms

+

The migration script handles safe, mechanical transforms:

+
pwsh scripts/bwfc-migrate.ps1 -Path ./MyWebFormsApp -Output ./MyBlazorApp
+
+

What the Script Does

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TransformBeforeAfter
File renameProducts.aspxProducts.razor
Strip asp: prefix<asp:Button><Button>
Remove runatrunat="server"(removed)
Fix expressions<%: value %>@(value)
Fix data binding<%#: Item.Name %>@context.Name
Fix comments<%-- text --%>@* text *@
Fix URLshref="~/path"href="/path"
Strip directives<%@ Page ... %>@page "/route"
Remove wrappers<asp:Content ...>(removed)
Remove <form runat><form runat="server">(removed)
Fix type paramsItemType="NS.Class"TItem="Class"
Remove dead attrsEnableViewState, AutoEventWireup(removed)
+

Preview Mode

+

Use -WhatIf to see what would change without writing files:

+
pwsh scripts/bwfc-migrate.ps1 -Path ./MyWebFormsApp -Output ./MyBlazorApp -WhatIf
+
+

Output Structure

+

The script creates a Blazor Server project with:

+
MyBlazorApp/
+├── MyBlazorApp.csproj          # With Fritz.BlazorWebFormsComponents reference
+├── Program.cs                   # With AddBlazorWebFormsComponents()
+├── _Imports.razor               # With BWFC usings
+├── Components/
+│   ├── Layout/
+│   │   └── MainLayout.razor     # From Site.Master
+│   └── Pages/
+│       ├── Index.razor          # From Default.aspx
+│       ├── Products.razor       # From Products.aspx
+│       └── ...
+├── Models/                      # Copied from source
+└── Services/                    # Stub services for DataSource replacements
+
+

Step 3: Apply Copilot Skill

+

Open the migrated project in VS Code with GitHub Copilot. The webforms-migration skill provides transformation rules for structural changes the script couldn't handle.

+

Using the Skill

+

Ask Copilot to apply the skill to each file:

+
+

"Using the webforms-migration skill, migrate the code-behind for Products.razor"

+
+

The skill handles:

+
    +
  • Code-behind migration: Page_Load → OnInitializedAsync, event handlers → EventCallback
    • +
  • Data binding: SelectMethod → service injection + Items property
    • +
  • Navigation: Response.Redirect → NavigationManager.NavigateTo
    • +
  • Visibility: Visible="false" → @if conditional blocks
    • +
  • Route parameters: [QueryString] → [SupplyParameterFromQuery]
    • +
  • Template context: Adding Context="Item" to data-bound templates
    • +
+

Example: Code-Behind Migration

+

Before (Products.aspx.cs): +

public partial class Products : Page
+{
+    protected void Page_Load(object sender, EventArgs e)
+    {
+        if (!IsPostBack)
+        {
+            BindGrid();
+        }
+    }
+
+    public IQueryable<Product> GetProducts()
+    {
+        var db = new ProductContext();
+        return db.Products.OrderBy(p => p.Name);
+    }
+
+    protected void DeleteBtn_Click(object sender, EventArgs e)
+    {
+        // delete logic
+        Response.Redirect("~/Products");
+    }
+}
+

+

After (Products.razor.cs): +

public partial class Products : ComponentBase
+{
+    [Inject] private IProductService ProductService { get; set; } = default!;
+    [Inject] private NavigationManager NavigationManager { get; set; } = default!;
+
+    private List<Product> products = new();
+
+    protected override async Task OnInitializedAsync()
+    {
+        products = await ProductService.GetProductsAsync();
+    }
+
+    private async Task DeleteBtn_Click()
+    {
+        // delete logic
+        NavigationManager.NavigateTo("/Products");
+    }
+}
+

+

Step 4: Resolve Semantic Decisions

+

For the remaining ~15% of migration work, use the migration agent for guidance on architectural decisions:

+
+

"Using the migration agent, help me migrate the session state and authentication from my Web Forms app"

+
+

The agent guides decisions like:

+
    +
  • Session state → Scoped services or ProtectedSessionStorage
    • +
  • ASP.NET Identity → Blazor Identity with AuthenticationStateProvider
    • +
  • Entity Framework 6 → EF Core with async patterns
    • +
  • Global.asax → Program.cs middleware pipeline
    • +
  • Web.config → appsettings.json
    • +
  • HTTP Handlers/Modules → ASP.NET Core middleware
    • +
+

Step 5: Build and Verify

+
cd MyBlazorApp
+dotnet build
+dotnet run
+
+
+

Common Build Errors

+
    +
  • Missing service registrations: Add builder.Services.AddScoped<IMyService, MyService>() in Program.cs
    • +
  • Namespace mismatches: Update @using directives in _Imports.razor
    • +
  • Async mismatch: Add async/await to data access methods
    • +
+
+

Replacing DataSource Controls

+

Web Forms DataSource controls (SqlDataSource, ObjectDataSource, etc.) have no BWFC equivalent. Replace them with injected services:

+

Before: +

<asp:SqlDataSource ID="ProductsDS" runat="server"
+    ConnectionString="<%$ ConnectionStrings:DefaultConnection %>"
+    SelectCommand="SELECT * FROM Products" />
+<asp:GridView DataSourceID="ProductsDS" runat="server" />
+

+

After: +

@inject IProductService ProductService
+
+<GridView Items="products" TItem="Product" AutoGenerateColumns="true" />
+
+@code {
+    private List<Product> products = new();
+
+    protected override async Task OnInitializedAsync()
+    {
+        products = await ProductService.GetProductsAsync();
+    }
+}
+

+

Control Coverage

+

BWFC provides 52 Blazor components covering the most commonly used Web Forms controls:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CategoryControls
EditorAdRotator, BulletedList, Button, Calendar, CheckBox, CheckBoxList, DropDownList, FileUpload, HiddenField, HyperLink, Image, ImageButton, Label, LinkButton, ListBox, Literal, Localize, MultiView, Panel, PlaceHolder, RadioButton, RadioButtonList, Table, TextBox, View
DataDataGrid, DataList, DataPager, DetailsView, FormView, GridView, ListView, Repeater
ValidationCompareValidator, CustomValidator, ModelErrorMessage, RangeValidator, RegularExpressionValidator, RequiredFieldValidator, ValidationSummary
NavigationMenu, SiteMapPath, TreeView
LoginChangePassword, CreateUserWizard, Login, LoginName, LoginStatus, LoginView, PasswordRecovery
AJAXScriptManager, ScriptManagerProxy, Timer, UpdatePanel, UpdateProgress
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/Custom-Controls/index.html b/site/Migration/Custom-Controls/index.html new file mode 100644 index 000000000..e0c8b34f5 --- /dev/null +++ b/site/Migration/Custom-Controls/index.html @@ -0,0 +1,5372 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Custom Controls - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Migrating Custom Controls to Blazor

+

When migrating ASP.NET Web Forms applications to Blazor, you'll often encounter custom controls that inherit from WebControl or CompositeControl. The BlazorWebFormsComponents library provides adapter classes that allow you to migrate these controls with minimal code changes.

+

Roslyn Analyzer Support

+

The BlazorWebFormsComponents.Analyzers NuGet package provides automated code analysis and fixes to help with migration:

+
    +
  • BWFC001: Detects public properties missing [Parameter] attributes and provides a code fix to add them
    • +
+

Base attributes (ID, CssClass, Style) are automatically applied by the WebControl base class, so no analyzer is needed for that.

+

Install the analyzer: +

dotnet add package BlazorWebFormsComponents.Analyzers
+

+

The analyzer automatically highlights migration issues in your IDE and offers quick fixes. See the Analyzer README for details.

+

Overview

+

In Web Forms, custom controls are typically created by: +1. Inheriting from WebControl for simple controls with custom HTML rendering +2. Inheriting from CompositeControl for controls that contain child controls +3. Using HtmlTextWriter to generate HTML output

+

The BlazorWebFormsComponents library provides Blazor-compatible versions of these classes in the BlazorWebFormsComponents.CustomControls namespace.

+

HtmlTextWriter

+

The HtmlTextWriter class provides a familiar API for rendering HTML, similar to the Web Forms version. It buffers HTML output that is then converted to Blazor's render tree.

+

Key Methods

+
    +
  • Write(string) - Writes text to the output
    • +
  • WriteLine(string) - Writes text followed by a line terminator
    • +
  • AddAttribute(string, string) - Adds an attribute to the next tag
    • +
  • AddStyleAttribute(string, string) - Adds a CSS style to the next tag
    • +
  • RenderBeginTag(string) - Opens an HTML tag
    • +
  • RenderEndTag() - Closes the current HTML tag
    • +
+

Supported Enums

+
    +
  • HtmlTextWriterTag - Common HTML tags (Div, Span, Button, etc.)
    • +
  • HtmlTextWriterAttribute - Common HTML attributes (Id, Class, Style, etc.)
    • +
  • HtmlTextWriterStyle - Common CSS styles (Color, Width, Height, etc.)
    • +
+

WebControl Base Class

+

The WebControl class provides a base for simple custom controls. It inherits from BaseStyledComponent, giving you access to standard styling properties.

+

Migration Example

+

Original Web Forms Control:

+
using System.Web.UI;
+using System.Web.UI.WebControls;
+
+public class HelloLabel : WebControl
+{
+    public string Text { get; set; }
+    public string Prefix { get; set; }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.RenderBeginTag(HtmlTextWriterTag.Span);
+        writer.Write($"{Prefix} {Text}");
+        writer.RenderEndTag();
+    }
+}
+
+

Blazor Version:

+
using BlazorWebFormsComponents.CustomControls;
+using Microsoft.AspNetCore.Components;
+
+public class HelloLabel : WebControl
+{
+    [Parameter]
+    public string Text { get; set; }
+
+    [Parameter]
+    public string Prefix { get; set; }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        // Base attributes (ID, CssClass, Style) are automatically added
+        writer.RenderBeginTag(HtmlTextWriterTag.Span);
+        writer.Write($"{Prefix} {Text}");
+        writer.RenderEndTag();
+    }
+}
+
+

Key Differences

+
    +
  1. Add [Parameter] attributes to public properties that should accept values from markup
    2. +
  2. Base attributes are automatic - ID, CssClass, and Style are automatically added before your Render method is called
    3. +
  3. No runat="server" needed in Blazor markup
    4. +
+

Usage in Blazor

+
<HelloLabel Text="World" Prefix="Hello" CssClass="greeting" />
+
+

Renders as: +

<span class="greeting">Hello World</span>
+

+

CompositeControl Base Class

+

The CompositeControl class is for controls that contain child controls. It extends WebControl and provides child control management.

+

Migration Example

+

Original Web Forms Control:

+
using System.Web.UI;
+using System.Web.UI.WebControls;
+
+public class SearchBox : CompositeControl
+{
+    protected override void CreateChildControls()
+    {
+        Label label = new Label { Text = "Search:" };
+        TextBox textBox = new TextBox { ID = "searchQuery" };
+        Button button = new Button { Text = "Go" };
+
+        Controls.Add(label);
+        Controls.Add(textBox);
+        Controls.Add(button);
+    }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.AddAttribute(HtmlTextWriterAttribute.Class, "search-box");
+        writer.RenderBeginTag(HtmlTextWriterTag.Div);
+        RenderChildren(writer);
+        writer.RenderEndTag();
+    }
+}
+
+

Blazor Version:

+

For composite controls in Blazor, you have two approaches:

+ +
using BlazorWebFormsComponents.CustomControls;
+using Microsoft.AspNetCore.Components;
+
+// Simple label control
+public class SimpleLabel : WebControl
+{
+    [Parameter]
+    public string Text { get; set; }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.RenderBeginTag(HtmlTextWriterTag.Label);
+        writer.Write(Text);
+        writer.RenderEndTag();
+    }
+}
+
+// Simple button control  
+public class SimpleButton : WebControl
+{
+    [Parameter]
+    public string Text { get; set; }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.RenderBeginTag(HtmlTextWriterTag.Button);
+        writer.Write(Text);
+        writer.RenderEndTag();
+    }
+}
+
+// Composite control
+public class SearchBox : CompositeControl
+{
+    protected override void CreateChildControls()
+    {
+        var label = new SimpleLabel { Text = "Search:" };
+        var button = new SimpleButton { Text = "Go" };
+
+        Controls.Add(label);
+        Controls.Add(button);
+    }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        // Base attributes are automatically added
+        writer.AddAttribute(HtmlTextWriterAttribute.Class, "search-box");
+        writer.RenderBeginTag(HtmlTextWriterTag.Div);
+        RenderChildren(writer);
+        writer.RenderEndTag();
+    }
+}
+
+ +

For more complex scenarios, consider converting to a pure Blazor component:

+
@* SearchBox.razor *@
+@inherits BaseStyledComponent
+
+<div class="@CalculatedCssClass">
+    <label>Search:</label>
+    <input type="text" @bind="SearchQuery" />
+    <button @onclick="OnSearchClick">Go</button>
+</div>
+
+@code {
+    [Parameter]
+    public string SearchQuery { get; set; }
+
+    [Parameter]
+    public EventCallback<string> OnSearch { get; set; }
+
+    private async Task OnSearchClick()
+    {
+        await OnSearch.InvokeAsync(SearchQuery);
+    }
+
+    private string CalculatedCssClass => CssClassBuilder.Default("search-box")
+        .AddClass(CssClass, when: !string.IsNullOrEmpty(CssClass))
+        .Build();
+}
+
+

Best Practices

+

1. Base Attributes Are Automatically Applied

+

Base styling properties (ID, CssClass, Style) are automatically added to the HtmlTextWriter before your Render method is called. You don't need to call any method to include them:

+
protected override void Render(HtmlTextWriter writer)
+{
+    // Base attributes are already added automatically!
+    writer.RenderBeginTag(HtmlTextWriterTag.Div);
+    writer.Write("Content");
+    writer.RenderEndTag();
+}
+
+

2. Class Attribute Concatenation

+

The HtmlTextWriter automatically concatenates multiple class attributes:

+
// Base CssClass is already added
+writer.AddAttribute(HtmlTextWriterAttribute.Class, "my-control");  // Concatenated
+writer.RenderBeginTag(HtmlTextWriterTag.Div);
+// Results in: <div class="user-class my-control">
+
+

3. Mark Properties with [Parameter]

+

Don't forget to add [Parameter] to properties that should be settable from markup:

+
[Parameter]  // Required for Blazor parameter binding
+public string Text { get; set; }
+
+

4. Consider Pure Blazor for New Development

+

While the custom control adapters are useful for migration, consider using pure Blazor components for new development:

+
    +
  • Better performance (no HTML string generation)
    • +
  • Better tooling support
    • +
  • More idiomatic Blazor code
    • +
  • Easier to maintain
    • +
+

5. Child Control Limitations

+

The CompositeControl.RenderChildren() method only works with child controls that inherit from WebControl. For standard Blazor components, use the pure Blazor approach (Approach 2 above).

+

Migration Strategy

+
    +
  1. Start with simple controls - Migrate WebControl-based controls first as they're simpler
    2. +
  2. Test incrementally - Migrate and test one control at a time
    3. +
  3. Consider refactoring - If a control is complex, consider rewriting it as a pure Blazor component
    4. +
  4. Update child controls first - For composite controls, migrate child controls before the parent
    5. +
  5. Validate HTML output - Compare rendered HTML between Web Forms and Blazor versions
    6. +
+

Common Pitfalls

+

Missing Service Registration

+

Custom controls inherit from BaseWebFormsComponent which requires certain services. Make sure your Blazor app registers them:

+
// In Program.cs
+builder.Services.AddRouting();  // Provides LinkGenerator
+builder.Services.AddHttpContextAccessor();  // Provides IHttpContextAccessor
+
+

For testing environments, you can use mocks:

+
// In test setup
+Services.AddSingleton<LinkGenerator>(new Mock<LinkGenerator>().Object);
+Services.AddSingleton<IHttpContextAccessor>(new Mock<IHttpContextAccessor>().Object);
+
+

ViewState Dependencies

+

Web Forms ViewState is syntax-only in Blazor. If your control relies heavily on ViewState, you'll need to refactor to use: +- Component parameters +- Blazor state management (@bind, cascading values) +- Browser storage (localStorage, sessionStorage)

+

Examples in the Test Suite

+

The BlazorWebFormsComponents test suite includes several example custom controls:

+
    +
  • HelloLabel - Simple text rendering
    • +
  • CustomButton - Button with custom attributes
    • +
  • StyledDiv - Control with inline styles
    • +
  • SearchBox - Composite control with multiple children
    • +
  • FormGroup - Composite control with conditional children
    • +
+

See: /src/BlazorWebFormsComponents.Test/CustomControls/TestComponents/

+

Further Reading

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/CustomControl-BaseClasses/index.html b/site/Migration/CustomControl-BaseClasses/index.html new file mode 100644 index 000000000..5b647609d --- /dev/null +++ b/site/Migration/CustomControl-BaseClasses/index.html @@ -0,0 +1,5613 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Custom Control Base Classes - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Custom Control Base Classes and Planned Improvements

+

The BlazorWebFormsComponents library provides a set of base classes and utilities that make it easier to migrate ASP.NET Web Forms custom controls to Blazor. This guide documents the current inventory, explains how each maps to Web Forms equivalents, and outlines the five planned improvements (P1–P5) that will further close the gap.

+
+

Current BWFC Base Class Inventory

+

BaseWebFormsComponent

+

The foundation of all BWFC compatibility components. It provides:

+
    +
  • Core Web Forms properties: ID, CssClass, Style
    • +
  • Control tree emulation: FindControl(string id) for searching children
    • +
  • Enabled/Visible state: Controls rendering based on these properties
    • +
  • HtmlTextWriter integration: Automatic base attribute application
    • +
+

Maps to Web Forms: System.Web.UI.Control

+

Usage: +

public class MyControl : BaseWebFormsComponent
+{
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.RenderBeginTag(HtmlTextWriterTag.Div);
+        writer.Write("Hello");
+        writer.RenderEndTag();
+    }
+}
+

+

BaseStyledComponent

+

Extends BaseWebFormsComponent with comprehensive CSS styling support:

+
    +
  • Inherits: All from BaseWebFormsComponent
    • +
  • Adds: Full CSS style properties (Color, BackColor, BorderWidth, Font, etc.)
    • +
  • Provides: Helper methods for building styled CSS classes
    • +
  • Calculated properties: CalculatedCssClass, CalculatedStyle for computed CSS
    • +
+

Maps to Web Forms: System.Web.UI.WebControls.WebControl

+

Usage: +

public class StyledButton : BaseStyledComponent
+{
+    [Parameter]
+    public string Text { get; set; }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.AddAttribute(HtmlTextWriterAttribute.Class, CalculatedCssClass);
+        writer.AddAttribute(HtmlTextWriterAttribute.Style, CalculatedStyle);
+        writer.RenderBeginTag(HtmlTextWriterTag.Button);
+        writer.Write(Text);
+        writer.RenderEndTag();
+    }
+}
+

+

DataBoundComponent

+

For components that render lists of items (like a Repeater or GridView):

+
    +
  • Generic parameter <T>: The item type being rendered
    • +
  • Automatic child control creation: Maintains a Controls collection based on item data
    • +
  • Item lifetime management: Handles instantiation and cleanup per item
    • +
  • Supports child control discovery: FindControl searches across all item children
    • +
+

Maps to Web Forms: System.Web.UI.WebControls.DataBoundControl

+

Usage: +

public class MyRepeater : DataBoundComponent<Employee>
+{
+    protected override void CreateChildControls()
+    {
+        // Called for each item in the data source
+        // Build controls for the current item
+    }
+
+    public override void DataBind()
+    {
+        // Called when Items parameter changes
+        base.DataBind();
+    }
+}
+

+

WebControl (CustomControls namespace)

+

A base class for simple controls that render custom HTML without child controls:

+
    +
  • Inherits from: BaseStyledComponent
    • +
  • Provides: Automatic base attribute rendering (ID, Class, Style)
    • +
  • Pattern: Override Render(HtmlTextWriter) to generate HTML
    • +
+

Maps to Web Forms: System.Web.UI.WebControls.WebControl

+

Usage: +

public class Badge : WebControl
+{
+    [Parameter]
+    public string Text { get; set; }
+
+    [Parameter]
+    public string BadgeType { get; set; } = "info";
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.AddAttribute(HtmlTextWriterAttribute.Class, $"badge badge-{BadgeType}");
+        writer.RenderBeginTag(HtmlTextWriterTag.Span);
+        writer.Write(Text);
+        writer.RenderEndTag();
+    }
+}
+

+

CompositeControl

+

A base class for controls that contain child controls:

+
    +
  • Inherits from: WebControl
    • +
  • Provides: Controls collection for child control management
    • +
  • Supports: CreateChildControls() pattern for child control creation
    • +
  • Limitation: Currently only supports WebControl-based children
    • +
+

Maps to Web Forms: System.Web.UI.WebControls.CompositeControl

+

Usage: +

public class SearchForm : CompositeControl
+{
+    private Label label;
+    private TextBox textBox;
+    private Button button;
+
+    protected override void CreateChildControls()
+    {
+        label = new SimpleLabel { Text = "Search:" };
+        textBox = new SimpleTextBox { ID = "query" };
+        button = new SimpleButton { Text = "Go" };
+
+        Controls.Add(label);
+        Controls.Add(textBox);
+        Controls.Add(button);
+    }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.AddAttribute(HtmlTextWriterAttribute.Class, "search-form");
+        writer.RenderBeginTag(HtmlTextWriterTag.Form);
+        RenderChildren(writer);
+        writer.RenderEndTag();
+    }
+}
+

+

DataBoundControl

+

A base class for data-bound controls that uses traditional Web Forms data binding:

+
    +
  • Inherits from: WebControl
    • +
  • Provides: DataSource property and DataBind() method
    • +
  • Pattern: Populate Controls collection in CreateChildControls() based on bound data
    • +
  • Limitation: Does not integrate with HtmlTextWriter rendering
    • +
+

Maps to Web Forms: System.Web.UI.WebControls.DataBoundControl

+

Note: This class exists but is rarely used in BWFC. The newer DataBoundComponent<T> is preferred for most scenarios.

+

HtmlTextWriter

+

A familiar API for rendering HTML that buffers output and converts it to Blazor's render tree:

+
    +
  • Key methods: RenderBeginTag(), RenderEndTag(), Write(), AddAttribute(), AddStyleAttribute()
    • +
  • Supported enums: HtmlTextWriterTag, HtmlTextWriterAttribute, HtmlTextWriterStyle
    • +
  • Automatic ID rendering: If set via the ID property, it's rendered on the outer tag
    • +
  • Limitation: HTML5 tags and attributes are incomplete (see P3 below)
    • +
+

Maps to Web Forms: System.Web.UI.HtmlTextWriter

+

Usage: +

protected override void Render(HtmlTextWriter writer)
+{
+    writer.AddAttribute(HtmlTextWriterAttribute.Id, ID);
+    writer.AddAttribute(HtmlTextWriterAttribute.Class, "card");
+    writer.AddStyleAttribute(HtmlTextWriterStyle.Margin, "10px");
+    writer.RenderBeginTag(HtmlTextWriterTag.Div);
+
+    writer.RenderBeginTag(HtmlTextWriterTag.H3);
+    writer.Write(Title);
+    writer.RenderEndTag();
+
+    writer.Write(Content);
+    writer.RenderEndTag();  // Close div
+}
+

+
+

Web Forms → BWFC Base Class Mapping

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web FormsBWFCNotes
System.Web.UI.ControlBaseWebFormsComponentCore functionality; ID, CssClass, Style; FindControl support
System.Web.UI.WebControls.WebControlBaseStyledComponent or WebControlFull CSS styling properties; choose BaseStyledComponent for more features
System.Web.UI.WebControls.CompositeControlCompositeControlChild control management; currently limited to WebControl children
System.Web.UI.WebControls.DataBoundControlDataBoundComponent<T>Data-bound rendering with full child control lifecycle
System.Web.UI.HtmlTextWriterHtmlTextWriter (BWFC version)Familiar API for rendering; missing some HTML5 tags/attributes
+
+

The Five Planned Improvements (P1–P5)

+

Analysis of DepartmentPortal's custom controls revealed five key gaps in the current BWFC implementation. These improvements are prioritized by adoption impact and complexity.

+

P1: DataBoundWebControl — Data-Bound Rendering with HtmlTextWriter

+

Current State: +- DataBoundControl exists for traditional data binding, but it doesn't integrate with HtmlTextWriter +- DataBoundComponent<T> exists for component-based data binding, but doesn't support HtmlTextWriter rendering +- No single base class bridges both patterns

+

What's Missing: +A DataBoundWebControl<T> base class that: +- Inherits from WebControl +- Accepts a generic data source of type <T> +- Provides CreateChildControls() pattern for HtmlTextWriter-based rendering per item +- Handles item control instantiation and lifecycle +- Allows custom HTML rendering via HtmlTextWriter for each item

+

Example Use Case (DepartmentPortal):

+

The EmployeeDataGrid control renders a table with custom formatting:

+
public class EmployeeDataGrid : DataBoundWebControl<Employee>
+{
+    [Parameter]
+    public IEnumerable<Employee> Employees { get; set; }
+
+    protected override void CreateChildControls()
+    {
+        var writer = new HtmlTextWriter();
+        writer.RenderBeginTag(HtmlTextWriterTag.Table);
+        writer.AddAttribute(HtmlTextWriterAttribute.Class, "table");
+
+        foreach (var emp in Employees)
+        {
+            writer.RenderBeginTag(HtmlTextWriterTag.Tr);
+            writer.RenderBeginTag(HtmlTextWriterTag.Td);
+            writer.Write($"{emp.FirstName} {emp.LastName}");
+            writer.RenderEndTag();
+            writer.RenderEndTag();
+        }
+
+        writer.RenderEndTag();
+    }
+}
+
+

Proposed API: +

public abstract class DataBoundWebControl<T> : WebControl
+{
+    [Parameter]
+    public IEnumerable<T> DataSource { get; set; }
+
+    protected IEnumerable<T> Items => DataSource;
+
+    // Template for each item
+    protected virtual void CreateItemControls(T item, HtmlTextWriter writer)
+    {
+        // Override to render each item
+    }
+
+    protected sealed override void Render(HtmlTextWriter writer)
+    {
+        foreach (var item in Items)
+        {
+            CreateItemControls(item, writer);
+        }
+    }
+}
+

+

Impact: Enables migration of many enterprise controls (DataGrid, Repeater with custom formatting, custom list controls).

+
+

P2: TagKey + AddAttributesToRender — Auto-Rendering Outer Tag

+

Current State: +- WebControl requires manual outer tag management in the Render() method +- No automatic rendering of a container tag with attributes +- Developers must remember to add ID, Class, Style attributes manually

+

What's Missing: +- A TagKey property that specifies the outer HTML tag (e.g., HtmlTextWriterTag.Div) +- An AddAttributesToRender() method that collects all attributes to render +- Automatic outer tag rendering that calls AddAttributesToRender() before yielding to derived class

+

Example Use Case (DepartmentPortal):

+

The StarRating and NotificationBell controls are simple wrappers around HTML elements:

+
public class StarRating : WebControl
+{
+    [Parameter]
+    public int Rating { get; set; }
+
+    [Parameter]
+    public int MaxRating { get; set; } = 5;
+
+    protected override HtmlTextWriterTag TagKey => HtmlTextWriterTag.Div;
+
+    protected override void AddAttributesToRender(HtmlTextWriter writer)
+    {
+        base.AddAttributesToRender(writer);  // Adds ID, Class, Style
+        writer.AddAttribute("data-rating", Rating.ToString());
+        writer.AddAttribute("aria-label", $"Rating: {Rating} out of {MaxRating}");
+    }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.RenderBeginTag(TagKey);
+        for (int i = 0; i < MaxRating; i++)
+        {
+            writer.AddAttribute(HtmlTextWriterAttribute.Class, i < Rating ? "star-filled" : "star-empty");
+            writer.RenderBeginTag(HtmlTextWriterTag.Span);
+            writer.Write("★");
+            writer.RenderEndTag();
+        }
+        writer.RenderEndTag();
+    }
+}
+
+

Current workaround (verbose): +

protected override void Render(HtmlTextWriter writer)
+{
+    writer.AddAttribute(HtmlTextWriterAttribute.Id, ID);
+    writer.AddAttribute(HtmlTextWriterAttribute.Class, CalculatedCssClass);
+    writer.AddAttribute(HtmlTextWriterAttribute.Style, CalculatedStyle);
+    writer.AddAttribute("data-rating", Rating.ToString());
+    writer.RenderBeginTag(HtmlTextWriterTag.Div);
+    // ... content rendering
+    writer.RenderEndTag();
+}
+

+

Impact: Simplifies 80% of custom control migrations by eliminating boilerplate attribute handling.

+
+

P3: HtmlTextWriter Enum Expansion — HTML5 Tags, Attributes, and Styles

+

Current State: +- HtmlTextWriterTag enum covers most HTML4 tags but misses modern HTML5 semantics +- HtmlTextWriterAttribute lacks data-* attributes, ARIA roles, and accessibility attributes +- HtmlTextWriterStyle is missing modern CSS properties (flexbox, grid, transforms, transitions)

+

What's Missing:

+

HTML5 Tags: +

Nav, Section, Article, Header, Footer, Main, Figure, FigCaption,
+Details, Summary, Mark, Time, Dialog, Output, Progress, Meter
+

+

HTML5+ Attributes: +

data-* (dynamic attributes)
+aria-* (accessibility)
+role, placeholder, autocomplete, disabled, readonly, required,
+crossorigin, integrity, async, defer, type (on script), 
+rel (on link), itemprop, itemscope, itemtype, itemref
+

+

Modern CSS Properties: +

Flex, FlexDirection, FlexWrap, JustifyContent, AlignItems,
+Grid, GridTemplateColumns, GridTemplateRows, GridGap,
+Transform, Transition, Animation, Opacity, ScaleX, ScaleY,
+Rotate, SkewX, SkewY, Perspective
+

+

Example Use Case (DepartmentPortal):

+

The redesigned navigation component uses semantic HTML:

+
// Current limitation — no Nav, no data attributes
+protected override void Render(HtmlTextWriter writer)
+{
+    writer.RenderBeginTag(HtmlTextWriterTag.Div);  // Should be Nav
+    writer.Write("<nav>");  // Workaround: raw HTML string
+    // ...
+    writer.Write("</nav>");
+    writer.RenderEndTag();
+}
+
+// With P3 — cleaner, type-safe
+protected override void Render(HtmlTextWriter writer)
+{
+    writer.AddAttribute("data-role", "navigation");  // Currently must use raw string
+    writer.AddAttribute("aria-label", "Main navigation");
+    writer.RenderBeginTag(HtmlTextWriterTag.Nav);  // Will exist after P3
+    // ...
+    writer.RenderEndTag();
+}
+
+

Proposed Changes:

+
public enum HtmlTextWriterTag
+{
+    // Existing tags...
+
+    // HTML5 Semantic tags
+    Nav,
+    Section,
+    Article,
+    Header,
+    Footer,
+    Main,
+    Figure,
+    FigCaption,
+    Details,
+    Summary,
+    Mark,
+    Time,
+    Dialog,
+    Output,
+    Progress,
+    Meter
+}
+
+public enum HtmlTextWriterAttribute
+{
+    // Existing attributes...
+
+    // ARIA attributes
+    AriaLabel,
+    AriaLabelledBy,
+    AriaDescribedBy,
+    AriaHidden,
+    AriaPressed,
+    AriaChecked,
+    AriaSelected,
+    AriaExpanded,
+    AriaLevel,
+    AriaLive,
+    AriaAtomic,
+    AriaRelevant,
+    AriaRequired,
+    AriaInvalid,
+
+    // Standard attributes
+    Role,
+    Placeholder,
+    AutoComplete,
+    Disabled,
+    ReadOnly,
+    Required,
+    CrossOrigin,
+    Integrity,
+    Async,
+    Defer,
+    ItemProp,
+    ItemScope,
+    ItemType,
+    ItemRef,
+
+    // Data attributes (special handling for data-*)
+    Data  // Use: writer.AddAttribute("data-toggle", "modal")
+}
+
+public enum HtmlTextWriterStyle
+{
+    // Existing styles...
+
+    // Flexbox
+    Display,  // Already exists, but needed for flex
+    FlexDirection,
+    FlexWrap,
+    JustifyContent,
+    AlignItems,
+    AlignContent,
+    Flex,
+
+    // Grid
+    Grid,
+    GridTemplateColumns,
+    GridTemplateRows,
+    GridGap,
+    GridColumnStart,
+    GridColumnEnd,
+    GridRowStart,
+    GridRowEnd,
+
+    // Transforms
+    Transform,
+    TransformOrigin,
+    Perspective,
+    PerspectiveOrigin,
+
+    // Animations
+    Transition,
+    Animation,
+
+    // Other
+    Opacity,
+    Filter,
+    Cursor,
+    UserSelect,
+    ClipPath,
+    MaskImage
+}
+
+

Impact: Enables modern web design patterns without falling back to raw HTML strings; improves accessibility support.

+
+

P4: CompositeControl Child Rendering — Support Mixed Child Types

+

Current State: +- CompositeControl requires all children to be WebControl descendants +- Throws NotSupportedException if a child is not a WebControl +- Cannot mix WebControl children with raw markup or other component types

+

What's Missing: +- Ability to render children of mixed types (WebControl, markup, native Blazor components) +- RenderChildren() method that intelligently handles different child types +- Support for ChildContent as well as programmatically added controls

+

Example Use Case (DepartmentPortal):

+

The EmployeeCard contains a mix of controls and custom markup:

+
public class EmployeeCard : CompositeControl
+{
+    protected override void CreateChildControls()
+    {
+        Controls.Add(new Image { ImageUrl = emp.PhotoUrl });  // WebControl
+        Controls.Add(new Label { Text = emp.Name });         // WebControl
+
+        // Currently throws exception:
+        var customDiv = new Control();  // Not a WebControl
+        Controls.Add(customDiv);
+
+        // Want to add raw markup:
+        Controls.Add(new HtmlLiteral("<hr />"));  // Doesn't exist
+    }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.AddAttribute(HtmlTextWriterAttribute.Class, "employee-card");
+        writer.RenderBeginTag(HtmlTextWriterTag.Div);
+        RenderChildren(writer);  // Should handle all child types
+        writer.RenderEndTag();
+    }
+}
+
+

Proposed Solution:

+
public class CompositeControl : WebControl
+{
+    // Accept RenderFragment for mixed content
+    [Parameter]
+    public RenderFragment ChildContent { get; set; }
+
+    // Also support programmatic Controls collection with mixed types
+    protected void RenderChildren(HtmlTextWriter writer)
+    {
+        foreach (var child in Controls)
+        {
+            if (child is WebControl webControl)
+            {
+                webControl.Render(writer);
+            }
+            else if (child is IHtmlContent htmlContent)
+            {
+                writer.Write(htmlContent.ToHtmlString());
+            }
+            else if (child is string text)
+            {
+                writer.Write(text);
+            }
+            else
+            {
+                throw new InvalidOperationException($"Child type {child.GetType().Name} is not supported");
+            }
+        }
+    }
+}
+
+

Impact: Enables migration of complex composite controls (card layouts, dashboard widgets, multi-section panels).

+
+

P5: ITemplate → RenderFragment Bridge Pattern

+

Current State: +- Web Forms uses ITemplate for parameterized templates +- BWFC has no direct equivalent for Blazor's RenderFragment<T> +- Migrating ITemplate-based controls requires manual pattern translation

+

What's Missing: +- A bridge class that converts ITemplate interface to RenderFragment<T> +- Guidance on the new Blazor template pattern for custom controls +- Automated conversion examples

+

Example Use Case (DepartmentPortal):

+

The SectionPanel control uses ITemplate for flexible content:

+

Web Forms: +

<asp:SectionPanel runat="server">
+    <HeaderTemplate>
+        <h2>Announcements</h2>
+    </HeaderTemplate>
+    <ContentTemplate>
+        <asp:Repeater ID="Announcements" runat="server" />
+    </ContentTemplate>
+</asp:SectionPanel>
+

+

Current BWFC limitation: +- ITemplate doesn't translate directly to Blazor components +- Must manually define RenderFragment parameters

+

Proposed Bridge Solution:

+
public class SectionPanel : CompositeControl
+{
+    // Old Web Forms style (for migration compat)
+    [Parameter]
+    public ITemplate HeaderTemplate { get; set; }
+
+    [Parameter]
+    public ITemplate ContentTemplate { get; set; }
+
+    // New Blazor style (recommended)
+    [Parameter]
+    public RenderFragment Header { get; set; }
+
+    [Parameter]
+    public RenderFragment Content { get; set; }
+
+    protected override void Render(HtmlTextWriter writer)
+    {
+        writer.RenderBeginTag(HtmlTextWriterTag.Section);
+
+        if (Header != null)
+        {
+            writer.RenderBeginTag(HtmlTextWriterTag.Header);
+            // Render RenderFragment
+            writer.RenderEndTag();
+        }
+
+        if (Content != null)
+        {
+            writer.RenderBeginTag(HtmlTextWriterTag.Div);
+            // Render RenderFragment
+            writer.RenderEndTag();
+        }
+
+        writer.RenderEndTag();
+    }
+}
+
+

Usage Pattern Migration:

+

Before (Web Forms template): +

<asp:SectionPanel runat="server">
+    <HeaderTemplate>
+        <h2>Announcements</h2>
+    </HeaderTemplate>
+    <ContentTemplate>
+        <asp:Repeater ID="Announcements" runat="server">
+            <ItemTemplate>
+                <div><%# Eval("Title") %></div>
+            </ItemTemplate>
+        </asp:Repeater>
+    </ContentTemplate>
+</asp:SectionPanel>
+

+

After (Blazor RenderFragment): +

<SectionPanel>
+    <Header>
+        <h2>Announcements</h2>
+    </Header>
+    <Content>
+        @foreach (var ann in announcements)
+        {
+            <div>@ann.Title</div>
+        }
+    </Content>
+</SectionPanel>
+

+

Impact: Enables migration of complex templated controls (dashboards, wizard steps, accordion panels with custom item layouts).

+
+

Summary: P1–P5 Priority and Dependencies

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PriorityFeatureImpactDependencies
P1DataBoundWebControl<T>High — bridges data binding + HtmlTextWriterNone; standalone
P2TagKey + AddAttributesToRenderHigh — simplifies 80% of control migrationsModerate refactor of WebControl
P3HtmlTextWriter enum expansionMedium — enables modern markup patternsLow; additive to existing enums
P4CompositeControl mixed childrenMedium — unlocks complex control migrationModerate; requires child type detection
P5ITemplate → RenderFragment bridgeLow — legacy pattern; most new controls use RenderFragmentLow; guidance + optional helper class
+

Recommended Implementation Order: P2 → P1 → P3 → P4 → P5

+

(P2 first because it unblocks the most migrations with the least effort.)

+
+

See Also

+ +
+

References

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/DeferredControls/index.html b/site/Migration/DeferredControls/index.html new file mode 100644 index 000000000..b59124268 --- /dev/null +++ b/site/Migration/DeferredControls/index.html @@ -0,0 +1,4895 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Deferred Controls - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Deferred Controls

+

Some ASP.NET Web Forms controls have been permanently deferred from implementation in this library. This page documents each deferred control, explains why it's excluded, and provides recommended alternatives for your Blazor migration.

+

Chart — Implemented

+
+

Chart is FULLY IMPLEMENTED

+

The Chart component has been implemented with Chart.js and supports 8 chart types: Column, Bar, Line, Pie, Area, Doughnut, Scatter (Point), and StackedColumn. See the Chart documentation for full details.

+
+

Unsupported Chart Types

+

The following 27 chart types from the Web Forms SeriesChartType enum are not supported and will throw NotSupportedException. If your application uses any of these, you will need an alternative approach:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Chart TypeAlternative
Stock, CandlestickUse a dedicated financial charting library (e.g., Lightweight Charts)
BubbleCan be approximated with a scatter chart and custom point sizes via Chart.js plugins
Radar, PolarChart.js supports these natively — consider a Chart.js plugin or custom integration
Funnel, PyramidUse a dedicated visualization library or custom SVG
Spline, SplineArea, SplineRangeUse Line/Area as an approximation; Chart.js tension options can create curved lines
StackedBar, StackedArea, StackedColumn100, StackedBar100, StackedArea100Use StackedColumn or Bar as a starting point; full stacking support may be added in a future release
Range, RangeBar, RangeColumnUse a dedicated charting library for range-style visualizations
BoxPlot, ErrorBarUse a statistical charting library
Renko, ThreeLineBreak, Kagi, PointAndFigureSpecialized financial chart types — use a dedicated financial charting library
FastPoint, FastLine, StepLineUse Point or Line respectively; Chart.js handles performance optimization automatically
+
+

Substitution — Implemented

+
+

Substitution is IMPLEMENTED

+

The Substitution component has been implemented as a migration compatibility component. In Web Forms, Substitution provided post-cache substitution; in Blazor, it renders callback output directly since all rendering is dynamic. See the Substitution documentation for full details.

+
+
+

Xml

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.xml?view=netframework-4.8

+

What It Did in Web Forms

+

The <asp:Xml> control displayed the contents of an XML document or the results of an XSLT transformation. It could take an XML source (inline, from a file, or from a System.Xml.XmlDocument) and optionally transform it using an XSLT stylesheet before rendering the output.

+
<asp:Xml ID="XmlDisplay" runat="server"
+         DocumentSource="~/App_Data/catalog.xml"
+         TransformSource="~/App_Data/catalog.xslt" />
+
+

Or with inline XML:

+
<asp:Xml ID="XmlInline" runat="server"
+         TransformSource="~/App_Data/transform.xslt">
+    <book>
+        <title>Blazor in Action</title>
+        <author>Chris Sainty</author>
+    </book>
+</asp:Xml>
+
+

Why It's Not Implemented

+

XSLT transforms via <asp:Xml> are a legacy pattern with near-zero adoption in modern projects:

+
    +
  • XSLT is rarely used in new development — it has been superseded by direct data binding, JSON APIs, and component-based rendering
    • +
  • The control existed for a very specific early-2000s pattern of XML-driven content rendering that has no meaningful migration demand
    • +
  • Building an XSLT transformation engine as a Blazor component would add complexity for a feature almost no one migrating to Blazor will need
    • +
+

What to Do Instead

+

Replace with direct data binding or Razor markup. If your Web Forms application used <asp:Xml> to display structured data, the Blazor equivalent is simply binding that data to components or HTML directly.

+

Before (Web Forms — XML + XSLT to render a list):

+
<asp:Xml ID="BookList" runat="server"
+         DocumentSource="~/App_Data/books.xml"
+         TransformSource="~/App_Data/books.xslt" />
+
+
<!-- books.xml -->
+<books>
+    <book><title>Blazor in Action</title><author>Chris Sainty</author></book>
+    <book><title>ASP.NET Core in Action</title><author>Andrew Lock</author></book>
+</books>
+
+
<!-- books.xslt -->
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+    <xsl:template match="/books">
+        <ul>
+            <xsl:for-each select="book">
+                <li><xsl:value-of select="title"/> by <xsl:value-of select="author"/></li>
+            </xsl:for-each>
+        </ul>
+    </xsl:template>
+</xsl:stylesheet>
+
+

After (Blazor — direct data binding):

+
<ul>
+    @foreach (var book in books)
+    {
+        <li>@book.Title by @book.Author</li>
+    }
+</ul>
+
+@code {
+    private List<Book> books;
+
+    protected override void OnInitialized()
+    {
+        books = BookService.GetBooks();
+    }
+}
+
+
+

If you genuinely need XSLT in Blazor

+

If your application logic truly depends on XSLT transformations (e.g., you receive XML from a third-party system and must apply an XSLT stylesheet), you can still use System.Xml.Xsl.XslCompiledTransform in your C# code and render the result as a MarkupString:

+
@((MarkupString)transformedHtml)
+
+@code {
+    private string transformedHtml;
+
+    protected override void OnInitialized()
+    {
+        var xslt = new XslCompiledTransform();
+        xslt.Load("transform.xslt");
+
+        using var writer = new StringWriter();
+        xslt.Transform("source.xml", null, writer);
+        transformedHtml = writer.ToString();
+    }
+}
+
+

This approach keeps the XSLT logic in C# where it belongs, rather than embedding it in a UI control.

+
+
+

Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ControlStatusRecommendation
Chart✅ CompleteImplemented with 8 chart types via Chart.js. Unsupported types need alternative libraries.
Substitution✅ CompleteImplemented — renders callback output directly. Post-cache substitution not applicable in Blazor.
Xml❌ DeferredUse XDocument + data binding or XslCompiledTransform + MarkupString
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/DeprecationGuidance/index.html b/site/Migration/DeprecationGuidance/index.html new file mode 100644 index 000000000..be2bbb844 --- /dev/null +++ b/site/Migration/DeprecationGuidance/index.html @@ -0,0 +1,6698 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Deprecation Guidance - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Deprecation Guidance: Web Forms Patterns Without Blazor Equivalents

+

This guide documents Web Forms patterns that do not have direct equivalents in Blazor. Understanding these differences is essential for successful migration from ASP.NET Web Forms to Blazor.

+
+

Why This Guide Exists

+

BlazorWebFormsComponents helps you reuse markup and familiar component APIs during migration. However, some Web Forms features were fundamentally tied to Web Forms architecture and cannot be replicated in Blazor. This guide helps you understand why these patterns are deprecated and what to use instead.

+
+
+

runat="server" Scope

+

What It Was

+

In ASP.NET Web Forms, every server control required the runat="server" attribute to signal the framework that the control should be processed server-side:

+
<asp:TextBox ID="txtName" runat="server" />
+<asp:Button ID="btnSubmit" runat="server" Text="Submit" OnClick="btnSubmit_Click" />
+
+

Without runat="server", the markup would be treated as literal HTML and not processed by the Web Forms runtime. This attribute was the bridge between client markup and server-side event handling.

+

Why It's Deprecated

+

Blazor components are always server-side by default (in Blazor Server) or rendered on the server (in Blazor WebAssembly with server-side prerendering). There is no concept of "client-side markup" that needs server-side processing — all components are inherently server-aware.

+

The runat="server" distinction existed because Web Forms served both static HTML and dynamic controls in the same file. Blazor components are always interactive by design.

+

What To Do Instead

+

Simply remove runat="server" when migrating:

+
+
+
+
<asp:TextBox ID="txtName" runat="server" />
+<asp:Button ID="btnSubmit" runat="server" Text="Submit" OnClick="btnSubmit_Click" />
+
+
+
+
<TextBox @bind-Value="name" />
+<Button Text="Submit" OnClick="HandleSubmit" />
+
+@code {
+    private string name = "";
+
+    private void HandleSubmit()
+    {
+        // Handle the submission
+    }
+}
+
+
+
+
+
+

Removal Strategy

+

Use Find and Replace in your editor to remove all runat="server" attributes. Example pattern: runat="server"\s+ → `` (empty string). This is a safe global replacement with no side effects.

+
+
+

ViewState

+

What It Was

+

Web Forms' ViewState was a key-value store that persisted control and page state across postbacks:

+
// Store data
+ViewState["UserID"] = 42;
+
+// Retrieve data
+int userId = (int)ViewState["UserID"];
+
+

The state was serialized, Base64-encoded, and stored as a hidden __VIEWSTATE input field in the rendered HTML. On postback, the framework deserialized this field to restore the page state.

+

Problems with ViewState: +- Hidden field could grow to megabytes if not carefully managed +- Serialization/deserialization added overhead +- Boxing and unboxing of objects reduced performance +- Encouraged anti-patterns of storing complex objects

+

Why It's Deprecated

+

Blazor components maintain state natively in memory. There is no postback cycle — components are persistent objects on the server (in Blazor Server) with their fields and properties intact throughout the user's session.

+

BlazorWebFormsComponents does provide a ViewState property for migration compatibility, but it's an anti-pattern in modern Blazor development.

+

What To Do Instead

+

Replace ViewState usage with strongly-typed component fields and properties:

+
+
+
+
// In Web Forms Page
+protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        ViewState["UserID"] = 42;
+        ViewState["UserName"] = "John Doe";
+    }
+}
+
+protected void btnLoad_Click(object sender, EventArgs e)
+{
+    int userId = (int)ViewState["UserID"];
+    string userName = (string)ViewState["UserName"];
+    lblResult.Text = $"User: {userName} (ID: {userId})";
+}
+
+
+
+
<Label Text="@result" />
+<Button Text="Load" OnClick="HandleLoad" />
+
+@code {
+    private int userId = 42;
+    private string userName = "John Doe";
+    private string result = "";
+
+    private void HandleLoad()
+    {
+        result = $"User: {userName} (ID: {userId})";
+    }
+}
+
+
+
+
+

Benefits of this approach: +- ✅ Strongly typed — compile-time type checking +- ✅ No serialization overhead — just in-memory references +- ✅ Clearer code — field names are explicit, not string keys +- ✅ Better IDE support — IntelliSense works on fields

+

Storing Data Across Multiple Users

+

If you need to persist data across users (e.g., application-wide or session state), use dependency injection with scoped or singleton services:

+
// Program.cs
+builder.Services.AddScoped<AppStateService>();
+
+// AppStateService.cs
+public class AppStateService
+{
+    private Dictionary<string, object> _state = new();
+
+    public void Set(string key, object value) => _state[key] = value;
+    public object? Get(string key) => _state.TryGetValue(key, out var value) ? value : null;
+}
+
+// Component.razor
+@inject AppStateService AppState
+
+<Button Text="Store" OnClick="HandleStore" />
+
+@code {
+    private void HandleStore()
+    {
+        AppState.Set("UserID", 42);
+    }
+}
+
+
+

UpdatePanel / Partial Page Updates

+

What It Was

+

UpdatePanel enabled partial-page AJAX updates in Web Forms:

+
<asp:ScriptManager ID="ScriptManager1" runat="server" />
+
+<asp:UpdatePanel ID="UpdatePanel1" runat="server" UpdateMode="Conditional">
+    <ContentTemplate>
+        <asp:Label ID="lblStatus" runat="server" Text="Ready" />
+        <asp:Button ID="btnRefresh" runat="server" Text="Refresh" OnClick="btnRefresh_Click" />
+    </ContentTemplate>
+    <Triggers>
+        <asp:AsyncPostBackTrigger ControlID="btnRefresh" EventName="Click" />
+    </Triggers>
+</asp:UpdatePanel>
+
+

When triggered, the UpdatePanel would: +1. Post to the server via AJAX (not a full page post) +2. Re-render the content inside the UpdatePanel +3. Send back only that rendered HTML +4. Update the page without a full refresh

+

Without UpdatePanel, every button click or form submission caused a full page postback and reload.

+

Why It's Deprecated

+

Blazor's component model handles all rendering incrementally by default. There is no distinction between "partial" and "full" updates — every component re-render is a partial update via SignalR. The concept of UpdatePanel is unnecessary.

+

BlazorWebFormsComponents provides an UpdatePanel component purely as a structural wrapper for HTML compatibility (e.g., if your CSS targets a .update-panel class). The UpdateMode, Triggers, and AsyncPostBackTrigger properties have no effect.

+

What To Do Instead

+

Simply use Blazor component state and event handlers:

+
+
+
+
<asp:ScriptManager ID="ScriptManager1" runat="server" />
+
+<asp:UpdatePanel ID="UpdatePanel1" runat="server" UpdateMode="Conditional">
+    <ContentTemplate>
+        <asp:Label ID="lblStatus" runat="server" Text="Ready" />
+        <asp:Button ID="btnRefresh" runat="server" Text="Refresh" OnClick="btnRefresh_Click" />
+    </ContentTemplate>
+    <Triggers>
+        <asp:AsyncPostBackTrigger ControlID="btnRefresh" EventName="Click" />
+    </Triggers>
+</asp:UpdatePanel>
+
+
protected void btnRefresh_Click(object sender, EventArgs e)
+{
+    lblStatus.Text = $"Refreshed at {DateTime.Now:HH:mm:ss}";
+}
+
+
+
+
<Label Text="@status" />
+<Button Text="Refresh" OnClick="HandleRefresh" />
+
+@code {
+    private string status = "Ready";
+
+    private void HandleRefresh()
+    {
+        status = $"Refreshed at {DateTime.Now:HH:mm:ss}";
+    }
+}
+
+
+
+
+

Key differences: +- ✅ No ScriptManager needed +- ✅ No Triggers collection — event handlers update state directly +- ✅ No ContentTemplate wrapper — just place content between tags +- ✅ All re-rendering is automatic and incremental

+

If You're Using UpdatePanel for HTML Structure Only

+

If your CSS or JavaScript depends on the <div> or <span> wrapper that UpdatePanel provides, you can keep it:

+
<UpdatePanel>
+    <Label Text="@status" />
+    <Button Text="Refresh" OnClick="HandleRefresh" />
+</UpdatePanel>
+
+@code {
+    private string status = "Ready";
+
+    private void HandleRefresh()
+    {
+        status = $"Refreshed at {DateTime.Now:HH:mm:ss}";
+    }
+}
+
+

This renders a <div> (or <span> if you set RenderMode="Inline") and works identically to a Blazor component. However, in new code, prefer a plain <div> if the UpdatePanel wrapper is the only reason you're including it.

+
+

Page_Load / IsPostBack Lifecycle

+

What It Was

+

Web Forms had a strict page lifecycle with well-known event hooks:

+
protected override void OnInit(EventArgs e)
+{
+    base.OnInit(e);
+    // Controls are initialized
+}
+
+protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        // First load only — load initial data
+        LoadDropDownData();
+    }
+    else
+    {
+        // Postback — state already loaded from ViewState
+    }
+}
+
+protected override void OnPreRender(EventArgs e)
+{
+    base.OnPreRender(e);
+    // Last chance to update state before rendering
+}
+
+

The IsPostBack boolean indicated whether the page was: +- true — A form submission (user posted the page back to itself) +- false — Initial page load (user navigated to the page)

+

Why It's Deprecated

+

Blazor components use a different lifecycle model based on component initialization and parameter changes, not postbacks.

+

In Blazor Server: +- No postback concept — components stay alive in memory +- No IsPostBack — state is preserved naturally by the component instance +- Lifecycle is event-driven — triggered by initialization, parameter changes, and user interactions

+

What To Do Instead

+

Map Web Forms lifecycle methods to Blazor equivalents:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web FormsBlazorWhen It FiresPurpose
Page_InitOnInitializedAsyncOnce, when component first createsInitialize static data, set defaults
Page_Load (first load)OnInitializedAsync or OnParametersSetAsyncInitial component creationLoad data for first render
Page_Load (postback)Event handlersWhen user interactsHandle form submissions, button clicks
OnPreRenderOnAfterRenderAsyncAfter each render cycleAccess rendered DOM elements
+

Migration Patterns

+

Pattern 1: Initialize Data on First Load

+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        LoadDropDownData();
+        LoadInitialContent();
+    }
+}
+
+private void LoadDropDownData()
+{
+    // Load dropdown options
+}
+
+private void LoadInitialContent()
+{
+    // Load initial page content
+}
+
+
+
+
@implements IAsyncDisposable
+@code {
+    protected override async Task OnInitializedAsync()
+    {
+        await LoadDropDownData();
+        await LoadInitialContent();
+    }
+
+    private async Task LoadDropDownData()
+    {
+        // Load dropdown options
+    }
+
+    private async Task LoadInitialContent()
+    {
+        // Load initial page content
+    }
+
+    async ValueTask IAsyncDisposable.DisposeAsync()
+    {
+        // Optional: cleanup resources
+    }
+}
+
+
+
+
+

Pattern 2: React to Parameter Changes

+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        string id = Request.QueryString["id"];
+        if (!string.IsNullOrEmpty(id))
+        {
+            LoadData(id);
+        }
+    }
+}
+
+
+
+
@implements IAsyncDisposable
+
+<h3>Item: @itemName</h3>
+
+@code {
+    [Parameter]
+    public string? Id { get; set; }
+
+    private string itemName = "";
+
+    protected override async Task OnParametersSetAsync()
+    {
+        if (!string.IsNullOrEmpty(Id))
+        {
+            await LoadData(Id);
+        }
+    }
+
+    private async Task LoadData(string id)
+    {
+        // Load data based on ID
+    }
+
+    async ValueTask IAsyncDisposable.DisposeAsync()
+    {
+        // Optional: cleanup
+    }
+}
+
+
+
+
+

Pattern 3: Handle Form Submissions

+
+
+
+
<asp:Button ID="btnSubmit" runat="server" Text="Submit" OnClick="btnSubmit_Click" />
+
+<asp:Label ID="lblResult" runat="server" />
+
+
protected void btnSubmit_Click(object sender, EventArgs e)
+{
+    // Handle submission
+    lblResult.Text = "Form submitted!";
+}
+
+
+
+
<Button Text="Submit" OnClick="HandleSubmit" />
+
+<Label Text="@result" />
+
+@code {
+    private string result = "";
+
+    private void HandleSubmit()
+    {
+        result = "Form submitted!";
+    }
+}
+
+
+
+
+
+

Key Insight: No IsPostBack Needed

+

In Blazor, you almost never need an equivalent to IsPostBack. The component instance persists — state is preserved naturally. Initialize data in OnInitializedAsync, respond to parameter changes in OnParametersSetAsync, and handle user interactions via event handlers. That's it.

+
+
+

ScriptManager

+

What It Was

+

ScriptManager was a required page-level component that managed: +- Partial rendering coordination for UpdatePanel/AJAX +- Script registration for adding <script> blocks dynamically +- Web service proxies for calling server-side PageMethods +- Script mode selection (Debug vs. Release)

+
<asp:ScriptManager ID="ScriptManager1" runat="server" 
+                   EnablePartialRendering="true"
+                   EnablePageMethods="true" />
+
+<asp:UpdatePanel>
+    <ContentTemplate>
+        <asp:Label ID="lblResult" runat="server" />
+        <asp:Button ID="btnCall" runat="server" Text="Call Server" OnClick="btnCall_Click" />
+    </ContentTemplate>
+</asp:UpdatePanel>
+
+

Without ScriptManager, AJAX features didn't work.

+

Why It's Deprecated

+

Blazor handles all of these concerns natively: +- Partial rendering — Built into Blazor's component model (no UpdatePanel needed) +- Script registration — Use IJSRuntime for JavaScript interop +- Web service calls — Use HttpClient or dependency injection +- Script delivery — Handled by the ASP.NET Core runtime

+

ScriptManager was a "hub" that Web Forms used to coordinate features Blazor provides out of the box.

+

What To Do Instead

+

BlazorWebFormsComponents provides ScriptManager as a migration compatibility stub — it renders nothing and accepts all parameters silently. Include it during migration if it helps your markup compile, but remove it once migration is stable.

+

Option 1: Remove ScriptManager (Preferred)

+
+
+
+
<asp:ScriptManager ID="ScriptManager1" runat="server" EnablePageMethods="true" />
+
+<asp:Button ID="btnCall" runat="server" Text="Call Server" OnClick="btnCall_Click" />
+<asp:Label ID="lblResult" runat="server" />
+
+
[WebMethod]
+public static string GetData()
+{
+    return "Data from server";
+}
+
+protected void btnCall_Click(object sender, EventArgs e)
+{
+    // In Web Forms, PageMethods enabled calling GetData() from JavaScript
+}
+
+
+
+
<Button Text="Call Server" OnClick="HandleCall" />
+<Label Text="@result" />
+
+@code {
+    private string result = "";
+
+    private async Task HandleCall()
+    {
+        result = await GetDataAsync();
+    }
+
+    private async Task<string> GetDataAsync()
+    {
+        return "Data from server";
+    }
+}
+
+
+
+
+

Option 2: Keep ScriptManager During Migration

+

If removing <ScriptManager /> causes compilation errors during migration, include it temporarily:

+
<ScriptManager />  @* Will be removed in cleanup phase *@
+
+<Button Text="Call Server" OnClick="HandleCall" />
+<Label Text="@result" />
+
+@code {
+    private string result = "";
+
+    private async Task HandleCall()
+    {
+        result = await GetDataAsync();
+    }
+
+    private async Task<string> GetDataAsync()
+    {
+        return "Data from server";
+    }
+}
+
+

If You're Using JavaScript Interop

+

Replace ScriptManager's script registration with IJSRuntime:

+
+
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    string script = @"alert('Hello from Web Forms!');";
+    ScriptManager.RegisterStartupScript(this, GetType(), "startup", script, true);
+}
+
+
+
+
@inject IJSRuntime JS
+
+@code {
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            await JS.InvokeVoidAsync("eval", "alert('Hello from Blazor!');");
+        }
+    }
+}
+
+
+
+
+

Or better yet, call a proper JavaScript module function:

+
// mymodule.js
+export function showGreeting() {
+    alert('Hello from Blazor!');
+}
+
+
@inject IJSRuntime JS
+@implements IAsyncDisposable
+
+<Button Text="Greet" OnClick="HandleGreet" />
+
+@code {
+    private IJSObjectReference? module;
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            module = await JS.InvokeAsync<IJSObjectReference>("import", "./mymodule.js");
+        }
+    }
+
+    private async Task HandleGreet()
+    {
+        if (module is not null)
+        {
+            await module.InvokeVoidAsync("showGreeting");
+        }
+    }
+
+    async ValueTask IAsyncDisposable.DisposeAsync()
+    {
+        if (module is not null)
+        {
+            await module.DisposeAsync();
+        }
+    }
+}
+
+
+

Best Practice

+

Treat ScriptManager as scaffolding. Include it early in migration to keep pages compiling, then remove it completely as part of your cleanup phase. A Blazor page with <ScriptManager /> behaves identically to one without it — the component renders nothing and does nothing.

+
+
+

Server-Side Control Property Manipulation

+

What It Was

+

In Web Forms, you could manipulate control properties on the server in code-behind:

+
protected void Page_Load(object sender, EventArgs e)
+{
+    // Disable a textbox
+    txtEmail.Enabled = false;
+
+    // Hide a button
+    btnDelete.Visible = false;
+
+    // Set a label's text
+    lblStatus.Text = "Loading...";
+
+    // Add CSS classes dynamically
+    btnSubmit.CssClass = "btn btn-primary";
+}
+
+

This approach worked because Web Forms re-rendered the entire page on each postback, picking up the property changes.

+

Why It's Deprecated

+

Blazor uses reactive data binding. Control properties are derived from component state, not set imperatively.

+

In Blazor: +- ✅ Declarative — Properties come from component fields/parameters, not imperative assignments +- ✅ Reactive — When state changes, the UI automatically updates +- ✅ Debuggable — It's clear where each value comes from by looking at the template

+

What To Do Instead

+

Bind control properties to component fields:

+
+
+
+
<asp:TextBox ID="txtEmail" runat="server" />
+<asp:Button ID="btnDelete" runat="server" Text="Delete" />
+<asp:Label ID="lblStatus" runat="server" />
+<asp:Button ID="btnSubmit" runat="server" Text="Submit" CssClass="btn btn-default" />
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    txtEmail.Enabled = false;
+    btnDelete.Visible = false;
+    lblStatus.Text = "Loading...";
+    btnSubmit.CssClass = "btn btn-primary";
+}
+
+
+
+
<TextBox Disabled="true" />
+<Button Text="Delete" Visible="isDeleteVisible" />
+<Label Text="@status" />
+<Button Text="Submit" Class="@btnClass" />
+
+@code {
+    private bool isDeleteVisible = false;
+    private string status = "Loading...";
+    private string btnClass = "btn btn-primary";
+
+    protected override async Task OnInitializedAsync()
+    {
+        // Data is set declaratively in the template above
+        // These values are read from component fields
+    }
+}
+
+
+
+
+

Benefits: +- ✅ Template clearly shows what's displayed +- ✅ No "hidden" state changes in code-behind +- ✅ Easier to reason about the UI +- ✅ Better testability (state is explicit)

+
+

Application and Session State

+

What It Was

+

Web Forms provided HttpContext.Current.Application and HttpContext.Current.Session for sharing data:

+
// Store in Application state (shared across all users)
+HttpContext.Current.Application["UserCount"] = 42;
+
+// Retrieve
+int count = (int)HttpContext.Current.Application["UserCount"];
+
+// Store in Session state (per-user)
+Session["UserID"] = currentUser.Id;
+
+// Retrieve
+int userId = (int)Session["UserID"];
+
+
    +
  • Application state — Shared across all users, stored in server memory
    • +
  • Session state — Per-user, stored in server memory or external store (SQL Server, Redis)
    • +
+

Why It's Deprecated

+

Blazor uses dependency injection for state management. This is cleaner, more testable, and scales better:

+
    +
  • ✅ Singleton services — Equivalent to Application state (shared across all users)
    • +
  • ✅ Scoped services — Equivalent to Session state (per-connection/user)
    • +
  • ✅ Transient services — New instance per request
    • +
  • ✅ Type-safe — No casting or string keys
    • +
+

What To Do Instead

+

Use dependency injection with services:

+

Application State → Singleton Service

+
+
+
+
// Store
+HttpContext.Current.Application["UserCount"] = 42;
+
+// Retrieve
+int count = (int)HttpContext.Current.Application["UserCount"];
+
+
+
+
// Program.cs
+builder.Services.AddSingleton<AppStateService>();
+
+// AppStateService.cs
+public class AppStateService
+{
+    public int UserCount { get; set; }
+}
+
+// Component.razor
+@inject AppStateService AppState
+
+<Label Text="@AppState.UserCount.ToString()" />
+
+@code {
+    protected override void OnInitialized()
+    {
+        AppState.UserCount = 42;
+    }
+}
+
+
+
+
+

Session State → Scoped Service

+
+
+
+
// Store
+Session["UserID"] = currentUser.Id;
+
+// Retrieve
+int userId = (int)Session["UserID"];
+
+
+
+
// Program.cs
+builder.Services.AddScoped<UserSessionService>();
+
+// UserSessionService.cs
+public class UserSessionService
+{
+    public int? UserId { get; set; }
+}
+
+// Component.razor
+@inject UserSessionService UserSession
+
+<Label Text="@UserSession.UserId?.ToString()" />
+
+@code {
+    protected override void OnInitialized()
+    {
+        UserSession.UserId = currentUser.Id;
+    }
+}
+
+
+
+
+

Advantages: +- ✅ Type-safe — No casting required +- ✅ Dependency injection — Easy to mock in tests +- ✅ Scalable — Works with distributed caching (Redis, etc.) +- ✅ Clear ownership — Services are explicit dependencies

+
+

Data Binding Events (ItemDataBound, SelectedIndexChanged)

+

What It Was

+

Web Forms raised binding and change events that you could handle to customize rendered content:

+
<asp:Repeater ID="rptItems" runat="server" OnItemDataBound="rptItems_ItemDataBound">
+    <ItemTemplate>
+        <div><%# Eval("Name") %></div>
+        <asp:Label ID="lblPrice" runat="server" />
+    </ItemTemplate>
+</asp:Repeater>
+
+<asp:DropDownList ID="ddlCategory" runat="server" OnSelectedIndexChanged="ddlCategory_SelectedIndexChanged" />
+
+
protected void rptItems_ItemDataBound(object sender, RepeaterItemEventArgs e)
+{
+    // Customize each item as it's bound
+    if (e.Item.ItemType == ListItemType.Item || e.Item.ItemType == ListItemType.AlternatingItem)
+    {
+        decimal price = (decimal)DataBinder.Eval(e.Item.DataItem, "Price");
+        Label lblPrice = (Label)e.Item.FindControl("lblPrice");
+        lblPrice.Text = price.ToString("C");
+    }
+}
+
+protected void ddlCategory_SelectedIndexChanged(object sender, EventArgs e)
+{
+    // Handle selection change
+    int categoryId = int.Parse(ddlCategory.SelectedValue);
+    LoadProductsForCategory(categoryId);
+}
+
+

Why It's Deprecated

+

Blazor uses component templates with @context to handle data binding. There's no separate event — you just use the data directly in the template.

+

What To Do Instead

+

Use Blazor component templates:

+

Repeater-Style Binding

+
+
+
+
<asp:Repeater ID="rptItems" runat="server" OnItemDataBound="rptItems_ItemDataBound">
+    <ItemTemplate>
+        <div><%# Eval("Name") %></div>
+        <asp:Label ID="lblPrice" runat="server" />
+    </ItemTemplate>
+</asp:Repeater>
+
+
protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        rptItems.DataSource = GetItems();
+        rptItems.DataBind();
+    }
+}
+
+protected void rptItems_ItemDataBound(object sender, RepeaterItemEventArgs e)
+{
+    if (e.Item.ItemType == ListItemType.Item || e.Item.ItemType == ListItemType.AlternatingItem)
+    {
+        decimal price = (decimal)DataBinder.Eval(e.Item.DataItem, "Price");
+        Label lblPrice = (Label)e.Item.FindControl("lblPrice");
+        lblPrice.Text = price.ToString("C");
+    }
+}
+
+
+
+
<Repeater Items="items">
+    <ItemTemplate>
+        <div>@context.Name</div>
+        <Label Text="@context.Price.ToString("C")" />
+    </ItemTemplate>
+</Repeater>
+
+@code {
+    private List<Item>? items;
+
+    protected override async Task OnInitializedAsync()
+    {
+        items = await GetItemsAsync();
+    }
+
+    private async Task<List<Item>> GetItemsAsync()
+    {
+        // Load items
+        return new();
+    }
+}
+
+class Item
+{
+    public string Name { get; set; } = "";
+    public decimal Price { get; set; }
+}
+
+
+
+
+ +
+
+
+
<asp:DropDownList ID="ddlCategory" runat="server" 
+                  OnSelectedIndexChanged="ddlCategory_SelectedIndexChanged"
+                  AutoPostBack="true" />
+<asp:Repeater ID="rptProducts" runat="server">
+    <ItemTemplate>
+        <div><%# Eval("Name") %></div>
+    </ItemTemplate>
+</asp:Repeater>
+
+
protected void ddlCategory_SelectedIndexChanged(object sender, EventArgs e)
+{
+    int categoryId = int.Parse(ddlCategory.SelectedValue);
+    LoadProductsForCategory(categoryId);
+}
+
+private void LoadProductsForCategory(int categoryId)
+{
+    rptProducts.DataSource = GetProducts(categoryId);
+    rptProducts.DataBind();
+}
+
+
+
+
<DropDownList Items="categories" 
+              @bind-Value="selectedCategoryId" 
+              OnChange="HandleCategoryChange" />
+
+<Repeater Items="products">
+    <ItemTemplate>
+        <div>@context.Name</div>
+    </ItemTemplate>
+</Repeater>
+
+@code {
+    private List<Category> categories = new();
+    private List<Product> products = new();
+    private string selectedCategoryId = "";
+
+    protected override async Task OnInitializedAsync()
+    {
+        categories = await GetCategoriesAsync();
+    }
+
+    private async Task HandleCategoryChange()
+    {
+        if (int.TryParse(selectedCategoryId, out int categoryId))
+        {
+            products = await GetProductsAsync(categoryId);
+        }
+    }
+
+    private async Task<List<Category>> GetCategoriesAsync() { /* ... */ return new(); }
+    private async Task<List<Product>> GetProductsAsync(int categoryId) { /* ... */ return new(); }
+}
+
+
+
+
+

Key differences: +- ✅ No separate ItemDataBound event — use @context in the template +- ✅ No FindControl — data is directly accessible +- ✅ No casting — types are strongly checked +- ✅ Reactive — updating products or selectedCategoryId automatically re-renders

+
+

Summary Migration Checklist

+

As you encounter Web Forms patterns during migration, refer to this checklist:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web Forms PatternActionBlazor Alternative
runat="server"RemoveAll components are server-side in Blazor
ViewStateReplaceComponent fields, scoped/singleton services
UpdatePanelRemove or keep for CSSBlazor's incremental rendering is automatic
ScriptManagerRemove (keep temporarily if needed)IJSRuntime, HttpClient
Page_LoadReplaceOnInitializedAsync, event handlers
IsPostBackRemoveComponent instance persistence
Page_InitReplaceOnInitializedAsync
Server control propertiesBindComponent fields, reactive data binding
Application stateReplaceSingleton services
Session stateReplaceScoped services
ItemDataBound eventReplaceBlazor templates with @context
SelectedIndexChanged eventReplaceOnChange, event handlers
+
+

Next Steps

+
    +
  1. Review your Web Forms codebase for patterns in this guide
    2. +
  2. Plan your migration using the Migration Strategies document
    3. +
  3. Use the Automated Migration Guide for your initial conversion
    4. +
  4. Test thoroughly — visual regression is common after migration
    5. +
  5. Gradually refactor — don't try to modernize everything at once
    6. +
+

For more guidance, see: +- Migration Strategies +- Automated Migration Guide +- Master Pages Migration +- User Controls Migration +- Page Service Documentation

+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/FindControl-Migration/index.html b/site/Migration/FindControl-Migration/index.html new file mode 100644 index 000000000..b17ebaf6c --- /dev/null +++ b/site/Migration/FindControl-Migration/index.html @@ -0,0 +1,5535 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FindControl Migration - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Migrating Away from FindControl

+

FindControl is a Web Forms method that allows you to locate a control in the page's control tree by its ID. While powerful, it's one of the most problematic patterns to migrate to Blazor because Blazor uses a component-based architecture with no "control tree" in the Web Forms sense.

+

This guide explains the FindControl problem, why it's difficult to migrate, and the idiomatic Blazor solutions.

+
+

What FindControl Does in Web Forms

+

FindControl(string id) searches the control hierarchy for a control with the specified ID:

+
// Web Forms Page code-behind
+protected void Page_Load(object sender, EventArgs e)
+{
+    TextBox searchBox = (TextBox)FindControl("SearchBox");
+    if (searchBox != null)
+    {
+        searchBox.Text = "Initial value";
+    }
+}
+
+

It returns null if the control is not found, which is why code often checks before using the result.

+

The search is shallow by default — it only searches direct children of the current container. To search deeper, you must either:

+
    +
  1. Recursively call FindControl on child containers, or
    2. +
  2. Understand naming container boundaries (explained below)
    3. +
+
+

The Naming Container Problem

+

A naming container is any control that implements INamingContainer. These include:

+
    +
  • Page — The top-level container
    • +
  • ContentPlaceHolder — Master page content areas
    • +
  • Panel with GroupingText
    • +
  • Custom controls inheriting from INamingContainer
    • +
+

The Problem: FindControl does not cross naming container boundaries. If a control is inside a naming container that is not a direct ancestor, FindControl cannot find it.

+

Example: The Master Page Boundary Problem

+

In DepartmentPortal, the master page contains a MessageLiteral control in the header:

+

Site.Master: +

<%@ Master Language="C#" %>
+<html>
+<head>
+    <title>Department Portal</title>
+</head>
+<body>
+    <form runat="server">
+        <div class="header">
+            <asp:Literal ID="MessageLiteral" runat="server" />
+        </div>
+
+        <asp:ContentPlaceHolder ID="MainContent" runat="server" />
+    </form>
+</body>
+</html>
+

+

MyPage.aspx (content page trying to access master's control): +

protected void Page_Load(object sender, EventArgs e)
+{
+    // This fails! FindControl cannot cross the ContentPlaceHolder boundary
+    var message = (Literal)FindControl("MessageLiteral");
+    // Result: null
+}
+

+

Why does it fail? The ContentPlaceHolder is a naming container. The page's FindControl searches within the page's container and the ContentPlaceHolder, but not the MasterPage's content (which is in a separate naming container managed by the master).

+

The Web Forms Fix: Access the master page directly:

+
protected void Page_Load(object sender, EventArgs e)
+{
+    // Cast Master to the specific master page type
+    var siteMaster = (Site)Master;
+    siteMaster.SetMessage("Welcome!");
+}
+
+

And add a public method to the master page code-behind:

+
// Site.Master.cs
+public void SetMessage(string text)
+{
+    MessageLiteral.Text = text;
+}
+
+

Example: The Template Container Problem

+

In DepartmentPortal, the SectionPanel control is a composite that uses ITemplate for child content:

+

SectionPanel.cs (Web Forms custom control): +

public class SectionPanel : CompositeControl, INamingContainer
+{
+    protected override void CreateChildControls()
+    {
+        var container = new Control();
+        Controls.Add(container);
+
+        if (ContentTemplate != null)
+        {
+            ContentTemplate.InstantiateIn(container);
+        }
+    }
+
+    [TemplateContainer(typeof(SectionPanel))]
+    public ITemplate ContentTemplate { get; set; }
+}
+

+

PageContent.aspx (content page with SectionPanel): +

<asp:SectionPanel ID="AnnouncementsSection" runat="server">
+    <ContentTemplate>
+        <asp:Repeater ID="AnnouncementsRepeater" runat="server" />
+    </ContentTemplate>
+</asp:SectionPanel>
+

+

PageContent.aspx.cs (trying to access repeater): +

protected void Page_Load(object sender, EventArgs e)
+{
+    // This fails! The Repeater is inside SectionPanel's template container
+    var repeater = (Repeater)FindControl("AnnouncementsRepeater");
+    // Result: null
+
+    // Correct approach: go through the panel
+    var panel = (SectionPanel)FindControl("AnnouncementsSection");
+    var repeater = (Repeater)panel.FindControl("AnnouncementsRepeater");
+}
+

+

Why? SectionPanel implements INamingContainer, creating a boundary. Controls inside the template are children of the panel's container, not the page.

+
+

Why FindControl Doesn't Translate to Blazor

+

Blazor uses a component-based architecture, not a control tree:

+
    +
  1. Components are not automatically indexed — Blazor components don't have a global registry
    2. +
  2. Component hierarchy is logical, not traversable — There is no "control tree" API
    3. +
  3. Parameters are explicit — Communication happens through parameters and cascading values, not search
    4. +
+

In Blazor, the equivalent of "finding a control by ID" is: +- Storing a direct reference via @ref +- Passing data through parameters +- Using cascading parameters for ancestor→descendant communication +- Using events for descendant→ancestor communication

+
+

Blazor Equivalents

+

Pattern 1: @ref for Direct References

+

Use @ref to store a reference to a component or HTML element:

+

Before (Web Forms): +

TextBox searchBox = (TextBox)FindControl("SearchBox");
+searchBox.Text = "Search here";
+

+

After (Blazor component): +

<SearchBox @ref="searchBoxRef" />
+
+@code {
+    private SearchBox searchBoxRef;
+
+    private void SetSearchText()
+    {
+        searchBoxRef.Text = "Search here";  // Requires public property on SearchBox
+    }
+}
+

+

Limitation: The child component must expose the property publicly.

+

Pattern 2: Parameters for Configuration

+

Instead of finding and modifying a control after creation, pass the desired state as a parameter:

+

Before (Web Forms — find and configure): +

protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        TextBox nameBox = (TextBox)FindControl("NameTextBox");
+        nameBox.Text = currentUser.Name;
+    }
+}
+

+
<asp:TextBox ID="NameTextBox" runat="server" />
+
+

After (Blazor — pass as parameter): +

<NameEditor InitialValue="currentUser.Name" />
+

+
@* NameEditor.razor *@
+<input type="text" value="@InitialValue" />
+
+@code {
+    [Parameter]
+    public string InitialValue { get; set; }
+}
+
+

Pattern 3: Cascading Parameters for Ancestor Communication

+

Use cascading parameters to allow deep component hierarchies to access ancestor state:

+

Before (Web Forms — find in master page): +

// Content page code-behind
+protected void ShowAlert(string message)
+{
+    var master = (SiteMaster)Master;
+    master.DisplayAlert(message);  // Requires public method on master
+}
+

+

After (Blazor — cascading parameter): +

@* App.razor or MainLayout.razor *@
+<CascadingValue Value="this">
+    @Body
+</CascadingValue>
+
+@code {
+    public void DisplayAlert(string message) { /* ... */ }
+}
+
+@* Any descendant component *@
+@code {
+    [CascadingParameter]
+    public MainLayout Layout { get; set; }
+
+    private void ShowAlert(string message)
+    {
+        Layout?.DisplayAlert(message);
+    }
+}
+

+

Pattern 4: EventCallback for Sibling/Child Communication

+

Use EventCallback<T> to communicate upward from child to parent:

+

Before (Web Forms — repeater item command): +

protected void EmployeeRepeater_ItemCommand(object source, RepeaterCommandEventArgs e)
+{
+    if (e.CommandName == "Delete")
+    {
+        int employeeId = (int)e.CommandArgument;
+        DeleteEmployee(employeeId);
+    }
+}
+

+

After (Blazor — event callback): +

@* Parent *@
+<EmployeeList OnDeleteRequested="HandleDelete" />
+
+@code {
+    private async Task HandleDelete(int employeeId)
+    {
+        await DeleteEmployee(employeeId);
+    }
+}
+
+@* Child (EmployeeList.razor) *@
+<button @onclick="() => OnDeleteRequested.InvokeAsync(employeeId)">Delete</button>
+
+@code {
+    [Parameter]
+    public EventCallback<int> OnDeleteRequested { get; set; }
+}
+

+

Pattern 5: Dependency Injection for Cross-Cutting Concerns

+

For global services (authentication, logging, settings), use DI instead of searching:

+

Before (Web Forms — find global master control): +

var userLabel = (Label)FindControl("UserLabel");  // Unreliable
+userLabel.Text = GetCurrentUserName();
+

+

After (Blazor — inject service): +

@inject AuthService Auth
+
+<span>Welcome, @Auth.CurrentUser.Name</span>
+
+@code {
+    protected override async Task OnInitializedAsync()
+    {
+        await Auth.LoadUserAsync();
+    }
+}
+

+
+

BWFC's FindControl — What It Does

+

The BaseWebFormsComponent class provides a FindControl method that matches the Web Forms API name:

+
public class BaseWebFormsComponent : ComponentBase
+{
+    public BaseWebFormsComponent FindControl(string id)
+    {
+        // Recursively searches this component and all descendants for matching ID
+    }
+}
+
+

What it does: Searches the current component's child controls and all descendants recursively for one with the matching ID. This mirrors the deep-search behavior that migrated Web Forms code typically expects.

+
+

Complete DepartmentPortal Migration Examples

+

Example 1: Master Page Message Control

+

Original Web Forms: +

// Site.Master.cs
+public void SetMessage(string message)
+{
+    MessageLiteral.Text = message;
+}
+
+// MyPage.aspx.cs
+protected void Page_Load(object sender, EventArgs e)
+{
+    ((Site)Master).SetMessage("Welcome!");
+}
+

+

Blazor Equivalent: +

@* MainLayout.razor *@
+<CascadingValue Value="this">
+    @Body
+</CascadingValue>
+
+<div class="message">@Message</div>
+
+@code {
+    public string Message { get; set; }
+
+    public void SetMessage(string message)
+    {
+        Message = message;
+        StateHasChanged();  // Trigger re-render
+    }
+}
+
+@* MyPage.razor *@
+@page "/"
+@inject MainLayout Layout
+
+<h1>Welcome</h1>
+
+@code {
+    protected override async Task OnInitializedAsync()
+    {
+        Layout.SetMessage("Welcome!");
+    }
+}
+

+

Example 2: SectionPanel with Repeater

+

Original Web Forms: +

<asp:SectionPanel ID="AnnouncementsSection" runat="server">
+    <ContentTemplate>
+        <asp:Repeater ID="AnnouncementsRepeater" runat="server" />
+    </ContentTemplate>
+</asp:SectionPanel>
+

+
protected void Page_Load(object sender, EventArgs e)
+{
+    var panel = (SectionPanel)FindControl("AnnouncementsSection");
+    var repeater = (Repeater)panel.FindControl("AnnouncementsRepeater");
+    repeater.DataSource = GetAnnouncements();
+    repeater.DataBind();
+}
+
+

Blazor Equivalent: +

<SectionPanel @ref="announcementsPanelRef">
+    <Repeater Items="announcements">
+        <ItemTemplate>
+            <div>@context.Title</div>
+        </ItemTemplate>
+    </Repeater>
+</SectionPanel>
+
+@code {
+    private SectionPanel announcementsPanelRef;
+    private List<Announcement> announcements = new();
+
+    protected override async Task OnInitializedAsync()
+    {
+        announcements = await GetAnnouncements();
+    }
+}
+

+

Key difference: The repeater is bound declaratively via the Items parameter, not through imperative FindControl + DataBind.

+

Example 3: Navigation Control with Active State

+

Original Web Forms: +

protected void Page_Load(object sender, EventArgs e)
+{
+    var navControl = (SidebarNav)FindControl("Navigation");
+    if (navControl != null)
+    {
+        navControl.SetActiveItem(GetCurrentPageName());
+    }
+}
+

+

Blazor Equivalent: +

<SidebarNav ActiveItem="currentPageName" />
+
+@code {
+    private string currentPageName;
+
+    protected override void OnInitialized()
+    {
+        currentPageName = GetCurrentPageName();
+    }
+}
+

+

Pattern: Pass the active item as a parameter instead of finding and calling a method.

+
+

Migration Patterns Table

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web Forms PatternProblemBlazor Solution
FindControl("ID") on direct childSimple lookupUse @ref reference
FindControl() for configurationLate-binding stateUse parameters instead
Access control in master pageNaming container boundaryExpose public method on master; call from derived page class
Access control in content placeholderNaming container boundaryPass as cascading parameter from master
Search repeater itemsDynamic control creationUse @foreach with direct references
Get control value to processImperative accessUse two-way binding @bind or parameters
Fire child control event from parentCross-component signalingUse @ref to call public method, or use event callbacks
Access sibling controlsLateral traversalUse parent as intermediary; communicate via parameters/events
+
+

Common Pitfalls

+

Pitfall 1: Assuming @ref Works Like FindControl

+

@ref only works for components and HTML elements in the current component's template. It does not recursively search child components.

+
@* Wrong — SearchBox is not a direct child *@
+<Container>
+    <SearchBox @ref="searchRef" />  @* Won't work *@
+</Container>
+
+@* Correct — hold reference to Container, not SearchBox *@
+<Container @ref="containerRef" />
+
+@code {
+    private Container containerRef;
+
+    private SearchBox GetSearchBox() => containerRef.SearchBoxRef;  @* Requires Container to expose it *@
+}
+
+

Pitfall 2: Forgetting to Check for Null

+

FindControl returns null if not found. Blazor's @ref is type-safe, but you must still null-check:

+
@code {
+    private SearchBox searchRef;
+
+    private void DoSomething()
+    {
+        if (searchRef != null)
+        {
+            searchRef.Focus();
+        }
+    }
+}
+
+

Pitfall 3: Modifying Control State After FindControl

+

FindControl returns a control you can modify, but in Blazor, parameters are one-way. Modifying a component via @ref bypasses the parameter binding and can cause inconsistency:

+
@* Problematic *@
+<TextBox @ref="textRef" Value="initialValue" />
+
+@code {
+    private TextBox textRef;
+
+    private void BadApproach()
+    {
+        textRef.Value = "new value";  @* Bypasses the Value parameter binding *@
+    }
+
+    private void GoodApproach()
+    {
+        // Instead, change state in parent and let it flow down
+        initialValue = "new value";
+        StateHasChanged();  @* Trigger re-render with new Value parameter *@
+    }
+}
+
+
+

See Also

+ +
+

References

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/MasterPages/index.html b/site/Migration/MasterPages/index.html new file mode 100644 index 000000000..a1e3d67ad --- /dev/null +++ b/site/Migration/MasterPages/index.html @@ -0,0 +1,6201 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Master Pages - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

MasterPages in BlazorWebFormsComponents

+

MasterPages in ASP.NET Web Forms provide a way to create a consistent layout and structure across multiple pages in a web application. In Blazor, this concept is replaced by Layouts, which use a similar pattern but with different syntax and mechanics.

+

The BlazorWebFormsComponents library provides MasterPage, ContentPlaceHolder, and Content components that bridge the gap between Web Forms and Blazor, allowing developers to maintain familiar syntax while leveraging Blazor's layout system.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.masterpage

+

Understanding MasterPages vs Blazor Layouts

+

Web Forms MasterPage Approach

+

In Web Forms, a MasterPage defines the template for your pages:

+
<!-- Site.Master -->
+<%@ Master Language="C#" %>
+<!DOCTYPE html>
+<html>
+<head runat="server">
+    <title><%: Page.Title %></title>
+</head>
+<body>
+    <form runat="server">
+        <div class="header">
+            <h1>My Website</h1>
+        </div>
+
+        <asp:ContentPlaceHolder ID="MainContent" runat="server">
+            <p>Default content if page doesn't override</p>
+        </asp:ContentPlaceHolder>
+
+        <div class="footer">
+            <p>&copy; 2024 My Company</p>
+        </div>
+    </form>
+</body>
+</html>
+
+

Child pages reference the master page:

+
<!-- MyPage.aspx -->
+<%@ Page Title="Home" Language="C#" MasterPageFile="~/Site.Master" %>
+
+<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server">
+    <h2>Welcome to my page!</h2>
+    <p>This is the content.</p>
+</asp:Content>
+
+

Blazor Layout Approach

+

In Blazor, layouts are components that inherit from LayoutComponentBase:

+
<!-- MainLayout.razor -->
+@inherits LayoutComponentBase
+
+<div class="header">
+    <h1>My Website</h1>
+</div>
+
+@Body
+
+<div class="footer">
+    <p>&copy; 2024 My Company</p>
+</div>
+
+

Pages use the @layout directive:

+
<!-- MyPage.razor -->
+@page "/"
+@layout MainLayout
+
+<h2>Welcome to my page!</h2>
+<p>This is the content.</p>
+
+

Using MasterPage Components in Blazor

+

The BlazorWebFormsComponents library provides components that allow you to use Web Forms-style syntax:

+

Creating a MasterPage

+
<!-- SiteMasterPage.razor -->
+@using BlazorWebFormsComponents
+
+<MasterPage>
+    <div class="header">
+        <h1>My Website</h1>
+        <nav>
+            <!-- Navigation menu -->
+        </nav>
+    </div>
+
+    <div class="main-content">
+        <ContentPlaceHolder ID="MainContent">
+            <p>Default content goes here</p>
+        </ContentPlaceHolder>
+    </div>
+
+    <div class="sidebar">
+        <ContentPlaceHolder ID="Sidebar">
+            <p>Default sidebar content</p>
+        </ContentPlaceHolder>
+    </div>
+
+    <div class="footer">
+        <p>&copy; @DateTime.Now.Year My Company</p>
+    </div>
+</MasterPage>
+
+

MasterPage with Head Parameter (Migration Helper)

+

The MasterPage component includes a Head parameter that automatically wraps content in a <HeadContent> component, providing a bridge between Web Forms' <head runat="server"> and Blazor's HeadContent. You can include <title> elements directly in the Head content:

+
<!-- SiteMasterPage.razor -->
+@using BlazorWebFormsComponents
+
+<MasterPage>
+    <Head>
+        <!-- This content is automatically wrapped in HeadContent -->
+        <title>My Website - Home</title>
+        <link href="css/site.css" rel="stylesheet" />
+        <meta name="description" content="My website" />
+    </Head>
+    <ChildContent>
+        <div class="header">
+            <h1>My Website</h1>
+        </div>
+
+        <ContentPlaceHolder ID="MainContent">
+            <p>Default content</p>
+        </ContentPlaceHolder>
+
+        <div class="footer">
+            <p>&copy; @DateTime.Now.Year My Company</p>
+        </div>
+    </ChildContent>
+</MasterPage>
+
+

How it works:

+

Head Parameter: +- Content placed in the <Head> parameter is automatically rendered inside a <HeadContent> component +- You can include <title> elements directly in the Head content and they will work correctly +- This allows you to maintain Web Forms-style head content definition in the MasterPage +- The content will be injected into the document's <head> section via the <HeadOutlet> in App.razor +- This bridges the gap between Web Forms' <head runat="server"> and Blazor's approach

+

Migration from Web Forms:

+

Before (Web Forms Site.Master): +

<%@ Master Language="C#" %>
+<!DOCTYPE html>
+<html>
+<head runat="server">
+    <title><%: Page.Title %> - My Site</title>
+    <link href="css/site.css" rel="stylesheet" />
+</head>
+<body>
+    <asp:ContentPlaceHolder ID="MainContent" runat="server">
+    </asp:ContentPlaceHolder>
+</body>
+</html>
+

+

After (Blazor MasterPage): +

<MasterPage>
+    <Head>
+        <title>@pageTitle - My Site</title>
+        <link href="css/site.css" rel="stylesheet" />
+    </Head>
+    <ChildContent>
+        <ContentPlaceHolder ID="MainContent">
+        </ContentPlaceHolder>
+    </ChildContent>
+</MasterPage>
+
+@code {
+    [Parameter] public string pageTitle { get; set; } = "Home";
+}
+

+

Important: While this parameter provides a convenient migration path, for new Blazor development, it's recommended to use <PageTitle> and <HeadContent> directly in your pages and layouts rather than centralizing all head content in a master page.

+

Multiple HeadContent Elements in the Hierarchy

+

Blazor's HeadContent components are additive - multiple <HeadContent> components throughout your component hierarchy all contribute to the final <head> section. This is important to understand when using the MasterPage's Head parameter.

+

How Multiple HeadContent Works

+

When you have HeadContent at multiple levels:

+
<!-- MasterPage -->
+<MasterPage>
+    <Head>
+        <!-- HeadContent #1: From MasterPage -->
+        <link href="css/site.css" rel="stylesheet" />
+    </Head>
+    <ChildContent>
+        <!-- Your layout here -->
+    </ChildContent>
+</MasterPage>
+
+<!-- Layout (if using one) -->
+@inherits LayoutComponentBase
+<HeadContent>
+    <!-- HeadContent #2: From Layout -->
+    <link href="css/layout.css" rel="stylesheet" />
+</HeadContent>
+@Body
+
+<!-- Page -->
+@page "/mypage"
+<HeadContent>
+    <!-- HeadContent #3: From Page -->
+    <link href="css/page.css" rel="stylesheet" />
+</HeadContent>
+
+<!-- Component within Page -->
+<HeadContent>
+    <!-- HeadContent #4: From Component -->
+    <link href="css/component.css" rel="stylesheet" />
+</HeadContent>
+
+

Result: All four HeadContent elements are collected by Blazor's <HeadOutlet> and rendered in the document's <head> section:

+
<head>
+    <!-- Static content from App.razor -->
+    <meta charset="utf-8" />
+
+    <!-- All HeadContent components combined -->
+    <link href="css/site.css" rel="stylesheet" />      <!-- From MasterPage.Head -->
+    <link href="css/layout.css" rel="stylesheet" />    <!-- From Layout -->
+    <link href="css/page.css" rel="stylesheet" />      <!-- From Page -->
+    <link href="css/component.css" rel="stylesheet" /> <!-- From Component -->
+</head>
+
+

Benefits of Additive HeadContent

+
    +
  1. Separation of Concerns - Each level can manage its own head content:
    2. +
  2. MasterPage/Layout: Site-wide styles and meta tags
    3. +
  3. Page: Page-specific SEO and styles
    4. +
  4. +

    Components: Component-specific resources

    +
    5. +
  5. +

    No Conflicts - Unlike Web Forms where the MasterPage owns the entire <head>, Blazor allows each level to contribute

    +
    6. +
  6. +

    Flexibility - Pages and components can add head content without modifying parent components

    +
    7. +
+

Migration Implications

+

When migrating from Web Forms:

+

Before (Web Forms): +

<!-- Site.Master - owns entire <head> -->
+<head runat="server">
+    <link href="css/site.css" rel="stylesheet" />
+    <asp:ContentPlaceHolder ID="HeadContent" runat="server">
+    </asp:ContentPlaceHolder>
+</head>
+
+<!-- MyPage.aspx - can only add via ContentPlaceHolder -->
+<asp:Content ContentPlaceHolderID="HeadContent" runat="server">
+    <link href="css/page.css" rel="stylesheet" />
+</asp:Content>
+

+

After (Blazor with MasterPage.Head): +

<!-- MasterPage -->
+<MasterPage>
+    <Head>
+        <link href="css/site.css" rel="stylesheet" />
+    </Head>
+    <ChildContent>...</ChildContent>
+</MasterPage>
+
+<!-- MyPage.razor - adds its own HeadContent -->
+@page "/mypage"
+<HeadContent>
+    <link href="css/page.css" rel="stylesheet" />
+</HeadContent>
+

+

Key Difference: In Blazor, both the MasterPage's Head parameter and the page's <HeadContent> work together additively. You don't need a ContentPlaceHolder in the head - pages can directly add HeadContent.

+

Best Practices

+
    +
  1. Use MasterPage.Head for site-wide content - CSS frameworks, global meta tags, fonts
    2. +
  2. Use page-level HeadContent for specifics - Page titles, descriptions, page-specific styles
    3. +
  3. Avoid duplication - Since all HeadContent is combined, be mindful of adding the same resource multiple times
    4. +
  4. Consider order - HeadContent from parent components renders before child components
    5. +
+

Example: Complete Hierarchy

+
<!-- App.razor -->
+<head>
+    <meta charset="utf-8" />
+    <HeadOutlet /> <!-- Collects all HeadContent -->
+</head>
+
+<!-- SiteMasterPage.razor -->
+<MasterPage>
+    <Head>
+        <!-- Site-wide resources -->
+        <link href="css/bootstrap.min.css" rel="stylesheet" />
+        <link href="css/site.css" rel="stylesheet" />
+    </Head>
+    <ChildContent>@ChildContent</ChildContent>
+</MasterPage>
+
+<!-- Products.razor -->
+@page "/products"
+<PageTitle>Products - My Store</PageTitle>
+<HeadContent>
+    <!-- Page-specific resources -->
+    <link href="css/products.css" rel="stylesheet" />
+    <meta name="description" content="Browse our products" />
+</HeadContent>
+
+<h1>Products</h1>
+<ProductCard /> <!-- Component with its own HeadContent -->
+
+<!-- ProductCard.razor (component) -->
+<HeadContent>
+    <!-- Component-specific resources (if needed) -->
+    <link href="css/product-card.css" rel="stylesheet" />
+</HeadContent>
+<div class="product-card">...</div>
+
+

Final HTML head: +

<head>
+    <meta charset="utf-8" />
+    <title>Products - My Store</title>
+    <link href="css/bootstrap.min.css" rel="stylesheet" />
+    <link href="css/site.css" rel="stylesheet" />
+    <link href="css/products.css" rel="stylesheet" />
+    <meta name="description" content="Browse our products" />
+    <link href="css/product-card.css" rel="stylesheet" />
+</head>
+

+

Using the MasterPage in a Page

+

While the components support Web Forms-style syntax, in practice you should use Blazor's native layout system for new development. These components are primarily useful for migration scenarios.

+

Features Supported

+

MasterPage Component

+
    +
  • ChildContent - the template content containing the layout structure and ContentPlaceHolder controls
    • +
  • Visible - controls visibility of the master page
    • +
  • Enabled - inherited from BaseWebFormsComponent
    • +
  • CssClass, BackColor, ForeColor - styling properties
    • +
+

ContentPlaceHolder Component

+
    +
  • ID - identifies the placeholder for matching with Content controls
    • +
  • ChildContent - default content displayed if no Content control provides a replacement
    • +
  • Visible - controls visibility of the content area
    • +
  • All styling properties from BaseWebFormsComponent
    • +
+

Content Component

+
    +
  • ContentPlaceHolderID - specifies which ContentPlaceHolder this content is for
    • +
  • ChildContent - the content to inject into the ContentPlaceHolder
    • +
  • Visible - controls visibility
    • +
+

Migration Strategy

+ +

The cleanest migration path is to convert MasterPages directly to Blazor layouts:

+

Before (Web Forms MasterPage): +

<%@ Master Language="C#" %>
+<asp:ContentPlaceHolder ID="MainContent" runat="server">
+</asp:ContentPlaceHolder>
+

+

After (Blazor Layout): +

@inherits LayoutComponentBase
+@Body
+

+

Before (Web Forms Page): +

<%@ Page MasterPageFile="~/Site.Master" %>
+<asp:Content ContentPlaceHolderID="MainContent" runat="server">
+    <h1>Hello</h1>
+</asp:Content>
+

+

After (Blazor Page): +

@page "/hello"
+@layout MainLayout
+<h1>Hello</h1>
+

+

Strategy 2: Using MasterPage Components for Gradual Migration

+

If you need to maintain Web Forms-style syntax temporarily:

+
    +
  1. Convert your .Master files to .razor components
    2. +
  2. Replace <%@ Master %> with <MasterPage> wrapper
    3. +
  3. Convert <asp:ContentPlaceHolder> to <ContentPlaceHolder>
    4. +
  4. In child pages, use standard Blazor syntax with layout directive
    5. +
+

Strategy 3: Nested MasterPages

+

Web Forms supports nested master pages. In Blazor, use nested layouts:

+
<!-- BaseLayout.razor -->
+@inherits LayoutComponentBase
+<div class="wrapper">
+    @Body
+</div>
+
+<!-- SiteLayout.razor -->
+@inherits LayoutComponentBase
+@layout BaseLayout
+<header>Header</header>
+@Body
+<footer>Footer</footer>
+
+

Key Differences

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureWeb FormsBlazor
File Extension.Master.razor
Directive<%@ Master %>@inherits LayoutComponentBase
Content Area<asp:ContentPlaceHolder>@Body or @RenderSection
Page Declaration<%@ Page MasterPageFile="~/Site.Master" %>@layout MainLayout
Multiple SectionsMultiple ContentPlaceHolders@RenderSection for named sections
Default ContentInside ContentPlaceHolder tagsNot typically used; define in layout
NestingMasterPageFile on master page@layout directive in layout component
HTML Head Management<head runat="server"> in MasterPage<HeadOutlet> in App.razor with <HeadContent> components
Page Title<%: Page.Title %> or Page.Title property<PageTitle> component
Scripts/StylesIn <head> or ContentPlaceHolders<HeadContent> component or <script>/<link> in App.razor
+

Managing HTML Head and Scripts

+

This is a critical difference between Web Forms MasterPages and Blazor layouts.

+

Web Forms MasterPage Head Management

+

In Web Forms, the MasterPage controls the entire HTML document including the <head> section:

+
<!-- Site.Master -->
+<%@ Master Language="C#" %>
+<!DOCTYPE html>
+<html>
+<head runat="server">
+    <meta charset="utf-8" />
+    <title><%: Page.Title %> - My Site</title>
+
+    <!-- Scripts can be added here -->
+    <asp:PlaceHolder runat="server">
+        <%: Scripts.Render("~/bundles/modernizr") %>
+    </asp:PlaceHolder>
+
+    <!-- Stylesheets -->
+    <link href="~/Content/site.css" rel="stylesheet" />
+
+    <!-- Child pages can add to head -->
+    <asp:ContentPlaceHolder ID="HeadContent" runat="server">
+    </asp:ContentPlaceHolder>
+</head>
+<body>
+    <!-- Body content -->
+</body>
+</html>
+
+

Child pages can add to the head:

+
<%@ Page Title="My Page" MasterPageFile="~/Site.Master" %>
+
+<asp:Content ContentPlaceHolderID="HeadContent" runat="server">
+    <link href="/css/custom.css" rel="stylesheet" />
+    <script src="/js/custom.js"></script>
+</asp:Content>
+
+

Blazor Head Management

+

In Blazor, the HTML structure is defined in App.razor (or _Host.cshtml in older versions), not in layouts:

+

App.razor (root component): +

<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <base href="/" />
+
+    <!-- Static stylesheets -->
+    <link rel="stylesheet" href="css/bootstrap/bootstrap.min.css" />
+    <link rel="stylesheet" href="css/site.css" />
+
+    <!-- HeadOutlet renders PageTitle and HeadContent from pages/layouts -->
+    <HeadOutlet />
+</head>
+<body>
+    <!-- Routes component renders pages with their layouts -->
+    <Routes />
+
+    <!-- Scripts at bottom of body -->
+    <script src="_framework/blazor.web.js"></script>
+    <script src="js/site.js"></script>
+</body>
+</html>
+

+

Individual Pages can add content to <head>: +

@page "/mypage"
+
+<PageTitle>My Page Title</PageTitle>
+
+<HeadContent>
+    <link href="css/custom.css" rel="stylesheet" />
+    <script src="js/custom.js"></script>
+    <meta name="description" content="My page description" />
+</HeadContent>
+
+<h1>Page Content</h1>
+

+

Layouts can also add head content: +

@inherits LayoutComponentBase
+
+<HeadContent>
+    <!-- Common head content for all pages using this layout -->
+    <link href="css/layout-specific.css" rel="stylesheet" />
+</HeadContent>
+
+<div class="page">
+    @Body
+</div>
+

+

Migration Strategy for Head Content

+

When migrating from Web Forms MasterPages to Blazor:

+

1. Move Static Head Content to App.razor

+

Content that applies to all pages should move from MasterPage to App.razor:

+

Before (Site.Master): +

<head runat="server">
+    <link href="~/Content/bootstrap.css" rel="stylesheet" />
+    <link href="~/Content/site.css" rel="stylesheet" />
+    <script src="~/Scripts/jquery.js"></script>
+</head>
+

+

After (App.razor): +

<head>
+    <link rel="stylesheet" href="css/bootstrap.css" />
+    <link rel="stylesheet" href="css/site.css" />
+    <HeadOutlet />
+</head>
+<body>
+    <Routes />
+    <script src="js/jquery.js"></script>
+</body>
+

+

2. Convert ContentPlaceHolder in Head to HeadContent

+

If your MasterPage has a ContentPlaceHolder in the <head>:

+

Before (Site.Master): +

<head runat="server">
+    <asp:ContentPlaceHolder ID="HeadContent" runat="server">
+    </asp:ContentPlaceHolder>
+</head>
+

+

Before (MyPage.aspx): +

<asp:Content ContentPlaceHolderID="HeadContent" runat="server">
+    <link href="/css/page-specific.css" rel="stylesheet" />
+</asp:Content>
+

+

After (MyPage.razor): +

@page "/mypage"
+
+<HeadContent>
+    <link href="css/page-specific.css" rel="stylesheet" />
+</HeadContent>
+

+

3. Convert Page.Title to PageTitle Component

+

Before (Site.Master): +

<head runat="server">
+    <title><%: Page.Title %> - My Site</title>
+</head>
+

+

Before (MyPage.aspx): +

<%@ Page Title="Home" MasterPageFile="~/Site.Master" %>
+

+

After (MyPage.razor): +

@page "/"
+
+<PageTitle>Home - My Site</PageTitle>
+

+

4. Script Management Strategies

+

Option A: Global Scripts in App.razor (Recommended) +

<!-- App.razor -->
+<body>
+    <Routes />
+    <script src="_framework/blazor.web.js"></script>
+    <script src="js/jquery.js"></script>
+    <script src="js/site.js"></script>
+</body>
+

+

Option B: Page-Specific Scripts with HeadContent +

<!-- MyPage.razor -->
+<HeadContent>
+    <script src="js/page-specific.js"></script>
+</HeadContent>
+

+

Option C: Dynamic Script Loading with IJSRuntime +

@inject IJSRuntime JS
+
+@code {
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            await JS.InvokeVoidAsync("loadScript", "js/dynamic.js");
+        }
+    }
+}
+

+

Important Limitations

+
    +
  1. +

    Layouts Don't Control HTML Structure - In Blazor, layouts only control the body content. The <html>, <head>, and <body> tags are defined in App.razor, not layouts.

    +
    2. +
  2. +

    No <head runat="server"> - Blazor doesn't have server-side head manipulation like Web Forms. Use <HeadContent> components instead.

    +
    3. +
  3. +

    Script Placement - Scripts are typically placed at the bottom of App.razor rather than in layouts or individual pages for better performance.

    +
    4. +
  4. +

    HeadOutlet is Required - You must include <HeadOutlet /> in your App.razor for <PageTitle> and <HeadContent> to work.

    +
    5. +
+

Example: Complete Head Migration

+

Before - Web Forms:

+

Site.Master: +

<%@ Master Language="C#" %>
+<!DOCTYPE html>
+<html>
+<head runat="server">
+    <title><%: Page.Title %> - Contoso</title>
+    <link href="~/Content/bootstrap.css" rel="stylesheet" />
+    <link href="~/Content/site.css" rel="stylesheet" />
+    <asp:ContentPlaceHolder ID="HeadContent" runat="server">
+    </asp:ContentPlaceHolder>
+</head>
+<body>
+    <asp:ContentPlaceHolder ID="MainContent" runat="server">
+    </asp:ContentPlaceHolder>
+    <script src="~/Scripts/jquery.js"></script>
+    <script src="~/Scripts/site.js"></script>
+</body>
+</html>
+

+

Products.aspx: +

<%@ Page Title="Products" MasterPageFile="~/Site.Master" %>
+
+<asp:Content ContentPlaceHolderID="HeadContent" runat="server">
+    <link href="/Content/products.css" rel="stylesheet" />
+    <meta name="description" content="Our products" />
+</asp:Content>
+
+<asp:Content ContentPlaceHolderID="MainContent" runat="server">
+    <h1>Our Products</h1>
+</asp:Content>
+

+

After - Blazor:

+

App.razor: +

<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <base href="/" />
+    <link rel="stylesheet" href="css/bootstrap.css" />
+    <link rel="stylesheet" href="css/site.css" />
+    <HeadOutlet />
+</head>
+<body>
+    <Routes />
+    <script src="_framework/blazor.web.js"></script>
+    <script src="js/jquery.js"></script>
+    <script src="js/site.js"></script>
+</body>
+</html>
+

+

MainLayout.razor: +

@inherits LayoutComponentBase
+
+<div class="page">
+    @Body
+</div>
+

+

Products.razor: +

@page "/products"
+
+<PageTitle>Products - Contoso</PageTitle>
+
+<HeadContent>
+    <link href="css/products.css" rel="stylesheet" />
+    <meta name="description" content="Our products" />
+</HeadContent>
+
+<h1>Our Products</h1>
+

+

Named Sections in Blazor

+

Blazor supports named sections similar to multiple ContentPlaceHolders:

+

Layout: +

@inherits LayoutComponentBase
+
+<header>
+    @RenderSection("Header", required: false)
+</header>
+
+<main>
+    @Body
+</main>
+
+<aside>
+    @RenderSection("Sidebar", required: false)
+</aside>
+

+

Page: +

@page "/mypage"
+
+@section Header {
+    <h1>Page Title</h1>
+}
+
+@section Sidebar {
+    <p>Sidebar content</p>
+}
+
+<p>Main content here</p>
+

+

Best Practices

+
    +
  1. Use Native Blazor Layouts - For new development, use Blazor's built-in layout system instead of MasterPage components
    2. +
  2. Convert During Migration - When migrating from Web Forms, take the opportunity to convert to Blazor layouts
    3. +
  3. Share Components - Extract shared UI into reusable Blazor components instead of relying solely on layouts
    4. +
  4. Cascading Values - Use cascading parameters to share data between layouts and pages
    5. +
  5. Consider RouteView - Blazor's RouteView component provides additional flexibility for layout assignment
    6. +
+

Example: Complete Migration

+

Before - Web Forms:

+

Site.Master: +

<%@ Master Language="C#" %>
+<html>
+<body>
+    <div class="header">Site Header</div>
+    <asp:ContentPlaceHolder ID="MainContent" runat="server">
+    </asp:ContentPlaceHolder>
+    <div class="footer">Footer</div>
+</body>
+</html>
+

+

Default.aspx: +

<%@ Page Title="Home" MasterPageFile="~/Site.Master" %>
+<asp:Content ContentPlaceHolderID="MainContent" runat="server">
+    <h1>Welcome</h1>
+</asp:Content>
+

+

After - Blazor:

+

MainLayout.razor: +

@inherits LayoutComponentBase
+
+<div class="header">Site Header</div>
+<main>
+    @Body
+</main>
+<div class="footer">Footer</div>
+

+

Index.razor: +

@page "/"
+@layout MainLayout
+
+<PageTitle>Home</PageTitle>
+<h1>Welcome</h1>
+

+

Web Forms Features NOT Supported

+

The following MasterPage features don't have direct equivalents in Blazor:

+
    +
  • <head runat="server"> - Blazor layouts don't control the HTML head. Use <HeadContent> components in pages/layouts, and define static head content in App.razor
    • +
  • Page.Title property - Use <PageTitle> component instead
    • +
  • ContentPlaceHolder in <head> - Use <HeadContent> component in pages instead
    • +
  • Master property - Not needed; layouts are applied via directive
    • +
  • MasterPageFile in web.config - Use @layout directive or configure in App.razor
    • +
  • MasterType directive - Not applicable in Blazor
    • +
  • FindControl across master/content - Use component references and cascading parameters
    • +
  • Server-side script registration - Use <HeadContent> with <script> tags or IJSRuntime for dynamic loading
    • +
+

Additional Resources

+ +

Conclusion

+

While the BlazorWebFormsComponents library provides MasterPage components for compatibility, the recommended approach for Blazor development is to use native layouts. These components are most valuable during migration to ease the transition from Web Forms to Blazor, but should be replaced with standard Blazor layouts as part of the modernization process.

+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/MigratingAshxHandlers/index.html b/site/Migration/MigratingAshxHandlers/index.html new file mode 100644 index 000000000..c026cea60 --- /dev/null +++ b/site/Migration/MigratingAshxHandlers/index.html @@ -0,0 +1,6328 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Migrating .ashx Handlers - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Migrating .ashx Handlers

+

Overview

+

ASP.NET Web Forms used .ashx files (HTTP Handler files) to handle HTTP requests directly, without the overhead of page lifecycle machinery. Handlers were ideal for serving file downloads, generating images, providing JSON APIs, and other request-response patterns that didn't need full page functionality.

+

In Blazor, there's no direct equivalent to .ashx handlers — but ASP.NET Core provides middleware, which is the modern way to intercept and handle HTTP requests. The BlazorWebFormsComponents library provides HttpHandlerBase, a base class that lets you port your .ashx logic to ASP.NET Core without rewriting your handler code, making migration straightforward and mechanical.

+

Why Migrate?

+
    +
  • .ashx files don't exist in .NET Core — your handlers will break when you move your application
    • +
  • ASP.NET Core's middleware is the modern, recommended approach
    • +
  • HttpHandlerBase provides a shim that preserves the familiar Web Forms HttpContext API, so you can migrate with ~6 mechanical changes per handler
    • +
  • Session state, file I/O, encoding — all supported
    • +
+
+

Quick Start: 6-Step Migration Checklist

+

Here are the mechanical changes required to migrate any .ashx handler to Blazor:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StepWeb FormsBlazor
1.using System.Web;using BlazorWebFormsComponents;
2.: IHttpHandler: HttpHandlerBase
3.ProcessRequest(HttpContext context)ProcessRequestAsync(HttpHandlerContext context) (async)
4.context.Response.End();return; (End is now [Obsolete])
5.Register in Program.csapp.MapHandler<T>("/path.ashx") declares handler route
6.Delete .ashx markup fileNo longer needed; handler is a plain C# class
+

Before registering handlers in Program.cs, verify: +- Session state handlers → mark with [RequiresSessionState] +- Complex paths → use explicit route pattern in MapHandler<T>()

+
+

Registration in Program.cs

+

HttpHandlerBase handlers are registered in your Blazor Program.cs using MapHandler<T>(), which integrates with the standard ASP.NET Core routing system.

+

Explicit Path Registration

+

Register a handler at a specific path using MapHandler<T>() in Program.cs:

+
// MyApp/FileDownloadHandler.cs
+public class FileDownloadHandler : HttpHandlerBase
+{
+    public override async Task ProcessRequestAsync(HttpHandlerContext context)
+    {
+        // ... handler logic ...
+    }
+}
+
+// Program.cs
+var builder = WebApplication.CreateBuilder(args);
+// ... other registrations ...
+
+var app = builder.Build();
+app.MapHandler<FileDownloadHandler>("/Handlers/FileDownload.ashx");
+app.Run();
+
+

Convention-Based Routing

+

If you omit the route pattern, the handler is registered at a derived path:

+
// MyApp/ProductApiHandler.cs
+public class ProductApiHandler : HttpHandlerBase
+{
+    public override async Task ProcessRequestAsync(HttpHandlerContext context)
+    {
+        // ... handler logic ...
+    }
+}
+
+// Program.cs — convention-based registration (no explicit path)
+app.MapHandler<ProductApiHandler>();
+// Convention: /ProductApi.ashx (class name minus "Handler" suffix + .ashx)
+// Accessible at: http://yourapp.com/ProductApi.ashx
+
+
+

Note

+

Convention-based routing derives the path from the class name. FileDownloadHandler → /FileDownload.ashx. Use MapHandler<T>("/custom/path") to override this behavior.

+
+

Multiple Paths for a Single Handler

+

Register one handler at multiple paths using MapHandler with varargs:

+
// Program.cs
+var app = builder.Build();
+
+app.MapHandler<FileDownloadHandler>("/Handlers/FileDownload.ashx", "/download.ashx", "/files/get");
+
+app.Run();
+
+

Chaining Authorization and CORS

+

Handlers support middleware chain configuration:

+
// Program.cs
+app.MapHandler<ApiHandler>("/api/Data.ashx")
+   .RequireAuthorization()
+   .WithOpenApi();
+
+app.MapHandler<FileHandler>("/Secure/Download.ashx")
+   .RequireAuthorization("AdminOnly")
+   .RequireCors("AllowFrontend");
+
+
+

Before/After Examples

+

Example 1: JSON API Handler (GET Request)

+

Web Forms (.ashx):

+
using System.Web;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace MyApp
+{
+    public class ProductApiHandler : IHttpHandler
+    {
+        public bool IsReusable => true;
+
+        public void ProcessRequest(HttpContext context)
+        {
+            context.Response.ContentType = "application/json";
+
+            var action = context.Request.QueryString["action"];
+
+            if (action == "list")
+            {
+                var products = GetProducts();
+                var json = JsonConvert.SerializeObject(products);
+                context.Response.Write(json);
+            }
+            else if (action == "count")
+            {
+                context.Response.Write("{\"count\":" + GetProducts().Count + "}");
+            }
+            else
+            {
+                context.Response.StatusCode = 400;
+                context.Response.Write("{\"error\":\"Unknown action\"}");
+            }
+        }
+
+        private List<Product> GetProducts()
+        {
+            return new List<Product>
+            {
+                new Product { Id = 1, Name = "Widget", Price = 9.99m },
+                new Product { Id = 2, Name = "Gadget", Price = 19.99m }
+            };
+        }
+    }
+}
+
+

Blazor (Migrated):

+
using BlazorWebFormsComponents;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json;
+
+namespace MyApp
+{
+    public class ProductApiHandler : HttpHandlerBase
+    {
+        public override async Task ProcessRequestAsync(HttpHandlerContext context)
+        {
+            context.Response.ContentType = "application/json";
+
+            var action = context.Request.QueryString["action"];
+
+            if (action == "list")
+            {
+                var products = GetProducts();
+                var json = JsonSerializer.Serialize(products);
+                context.Response.Write(json);
+            }
+            else if (action == "count")
+            {
+                context.Response.Write("{\"count\":" + GetProducts().Count + "}");
+            }
+            else
+            {
+                context.Response.StatusCode = 400;
+                context.Response.Write("{\"error\":\"Unknown action\"}");
+            }
+        }
+
+        private List<Product> GetProducts()
+        {
+            return new List<Product>
+            {
+                new Product { Id = 1, Name = "Widget", Price = 9.99m },
+                new Product { Id = 2, Name = "Gadget", Price = 19.99m }
+            };
+        }
+    }
+}
+
+

Changes Made: +1. using System.Web; → using BlazorWebFormsComponents; +2. : IHttpHandler → : HttpHandlerBase +3. ProcessRequest(HttpContext context) → async Task ProcessRequestAsync(HttpHandlerContext context) +4. Register with app.MapHandler<ProductApiHandler>("/api/Products.ashx") in Program.cs +5. JsonConvert → System.Text.Json.JsonSerializer (separate migration)

+
+

Example 2: File Download Handler (Binary Response)

+

Web Forms (.ashx):

+
using System;
+using System.IO;
+using System.Web;
+
+namespace MyApp
+{
+    public class FileDownloadHandler : IHttpHandler
+    {
+        public bool IsReusable => true;
+
+        public void ProcessRequest(HttpContext context)
+        {
+            var fileId = context.Request.QueryString["id"];
+
+            if (string.IsNullOrEmpty(fileId) || !int.TryParse(fileId, out var id))
+            {
+                context.Response.StatusCode = 400;
+                context.Response.ContentType = "text/plain";
+                context.Response.Write("Invalid file ID");
+                return;
+            }
+
+            // Look up file in database or file system
+            var filePath = context.Server.MapPath("~/App_Data/Files/" + fileId + ".pdf");
+
+            if (!File.Exists(filePath))
+            {
+                context.Response.StatusCode = 404;
+                context.Response.Write("File not found");
+                return;
+            }
+
+            var fileBytes = File.ReadAllBytes(filePath);
+            var fileName = Path.GetFileName(filePath);
+
+            context.Response.Clear();
+            context.Response.ContentType = "application/pdf";
+            context.Response.AddHeader("Content-Disposition", 
+                $"attachment; filename=\"{fileName}\"");
+            context.Response.BinaryWrite(fileBytes);
+            context.Response.End();
+        }
+    }
+}
+
+

Blazor (Migrated):

+
using BlazorWebFormsComponents;
+using System;
+using System.IO;
+
+namespace MyApp
+{
+    public class FileDownloadHandler : HttpHandlerBase
+    {
+        public override async Task ProcessRequestAsync(HttpHandlerContext context)
+        {
+            var fileId = context.Request.QueryString["id"];
+
+            if (string.IsNullOrEmpty(fileId) || !int.TryParse(fileId, out var id))
+            {
+                context.Response.StatusCode = 400;
+                context.Response.ContentType = "text/plain";
+                context.Response.Write("Invalid file ID");
+                return;
+            }
+
+            // Look up file in database or file system
+            var filePath = context.Server.MapPath("~/App_Data/Files/" + fileId + ".pdf");
+
+            if (!File.Exists(filePath))
+            {
+                context.Response.StatusCode = 404;
+                context.Response.Write("File not found");
+                return;
+            }
+
+            var fileBytes = File.ReadAllBytes(filePath);
+            var fileName = Path.GetFileName(filePath);
+
+            context.Response.Clear();
+            context.Response.ContentType = "application/pdf";
+            context.Response.AddHeader("Content-Disposition", 
+                $"attachment; filename=\"{fileName}\"");
+            context.Response.BinaryWrite(fileBytes);
+            // return; — Response.End() no longer needed
+        }
+    }
+}
+
+

Changes Made: +1. using System.Web; → using BlazorWebFormsComponents; +2. : IHttpHandler → : HttpHandlerBase +3. ProcessRequest(HttpContext context) → async Task ProcessRequestAsync(HttpHandlerContext context) +4. Removed context.Response.End(); — return statement is sufficient +5. Register with app.MapHandler<FileDownloadHandler>("/Handlers/FileDownload.ashx") in Program.cs

+
+

Example 3: Image Generation Handler (Thumbnail/Chart)

+

Web Forms (.ashx):

+
using System;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.IO;
+using System.Web;
+
+namespace MyApp
+{
+    public class ThumbnailHandler : IHttpHandler
+    {
+        public bool IsReusable => true;
+
+        public void ProcessRequest(HttpContext context)
+        {
+            var imagePath = context.Request.QueryString["path"];
+            var width = int.Parse(context.Request.QueryString["w"] ?? "150");
+            var height = int.Parse(context.Request.QueryString["h"] ?? "150");
+
+            if (string.IsNullOrEmpty(imagePath))
+            {
+                context.Response.StatusCode = 400;
+                context.Response.Write("Missing image path");
+                return;
+            }
+
+            var fullPath = context.Server.MapPath("~/Images/" + imagePath);
+            if (!File.Exists(fullPath))
+            {
+                context.Response.StatusCode = 404;
+                return;
+            }
+
+            try
+            {
+                using (var image = new Bitmap(fullPath))
+                {
+                    using (var thumbnail = image.GetThumbnailImage(width, height, 
+                        () => false, IntPtr.Zero))
+                    {
+                        context.Response.ContentType = "image/jpeg";
+                        using (var ms = new MemoryStream())
+                        {
+                            thumbnail.Save(ms, ImageFormat.Jpeg);
+                            context.Response.BinaryWrite(ms.ToArray());
+                        }
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                context.Response.StatusCode = 500;
+                context.Response.ContentType = "text/plain";
+                context.Response.Write("Error generating thumbnail: " + ex.Message);
+            }
+        }
+    }
+}
+
+

Blazor (Migrated):

+
using BlazorWebFormsComponents;
+using System;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.IO;
+
+namespace MyApp
+{
+    public class ThumbnailHandler : HttpHandlerBase
+    {
+        public override async Task ProcessRequestAsync(HttpHandlerContext context)
+        {
+            var imagePath = context.Request.QueryString["path"];
+            var width = int.Parse(context.Request.QueryString["w"] ?? "150");
+            var height = int.Parse(context.Request.QueryString["h"] ?? "150");
+
+            if (string.IsNullOrEmpty(imagePath))
+            {
+                context.Response.StatusCode = 400;
+                context.Response.Write("Missing image path");
+                return;
+            }
+
+            var fullPath = context.Server.MapPath("~/Images/" + imagePath);
+            if (!File.Exists(fullPath))
+            {
+                context.Response.StatusCode = 404;
+                return;
+            }
+
+            try
+            {
+                using (var image = new Bitmap(fullPath))
+                {
+                    using (var thumbnail = image.GetThumbnailImage(width, height, 
+                        () => false, IntPtr.Zero))
+                    {
+                        context.Response.ContentType = "image/jpeg";
+                        using (var ms = new MemoryStream())
+                        {
+                            thumbnail.Save(ms, ImageFormat.Jpeg);
+                            context.Response.BinaryWrite(ms.ToArray());
+                        }
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                context.Response.StatusCode = 500;
+                context.Response.ContentType = "text/plain";
+                context.Response.Write("Error generating thumbnail: " + ex.Message);
+            }
+        }
+    }
+}
+
+

Changes Made: +1. using System.Web; → using BlazorWebFormsComponents; +2. : IHttpHandler → : HttpHandlerBase +3. ProcessRequest(HttpContext context) → async Task ProcessRequestAsync(HttpHandlerContext context) +4. Register with app.MapHandler<ThumbnailHandler>("/Handlers/Thumbnail.ashx") in Program.cs

+
+

Note

+

Image generation logic transfers directly. No rewrite needed for System.Drawing code — the API is identical between Web Forms and Core.

+
+
+

API Reference

+

HttpHandlerContext

+

The context object passed to ProcessRequestAsync. It wraps the ASP.NET Core HttpContext and provides familiar Web Forms properties.

+
public class HttpHandlerContext
+{
+    public HttpHandlerRequest Request { get; }      // Request data
+    public HttpHandlerResponse Response { get; }    // Response output
+    public HttpHandlerServer Server { get; }        // Server utilities
+    public ISession? Session { get; }               // Session state (if [RequiresSessionState])
+    public ClaimsPrincipal User { get; }            // Current user principal
+    public IDictionary<object, object> Items { get; }  // Request-scoped items dictionary
+}
+
+
+

HttpHandlerRequest

+

Encapsulates HTTP request data: query strings, form data, headers, files.

+
public class HttpHandlerRequest
+{
+    // Query strings: context.Request.QueryString["id"]
+    public string? this[string key] { get; }
+    public NameValueCollection QueryString { get; }
+
+    // Form data (POST): context.Request.Form["field"]
+    public NameValueCollection Form { get; }
+
+    // File uploads: context.Request.Files["upload"]
+    public IFormFileCollection Files { get; }
+
+    // HTTP method: "GET", "POST", etc.
+    public string HttpMethod { get; }
+
+    // Request headers
+    public IHeaderDictionary Headers { get; }
+
+    // Request content type
+    public string? ContentType { get; }
+
+    // Raw request stream
+    public Stream InputStream { get; }
+
+    // Request URL information
+    public string Path { get; }
+    public string RawUrl { get; }
+    public string Url { get; }
+
+    // Is the request authenticated?
+    public bool IsAuthenticated { get; }
+
+    // Client IP address
+    public string RemoteAddr { get; }
+}
+
+

Common Usage:

+
var userId = context.Request.QueryString["id"];    // GET parameter
+var userName = context.Request.Form["username"];   // POST field
+var file = context.Request.Files["upload"];        // Uploaded file
+if (context.Request.IsAuthenticated)
+{
+    // User is logged in
+}
+
+
+

HttpHandlerResponse

+

Controls HTTP response output: content type, status code, headers, body content.

+
public class HttpHandlerResponse
+{
+    // Content type (e.g., "application/json", "image/png")
+    public string ContentType { get; set; }
+
+    // HTTP status code (200, 404, 500, etc.)
+    public int StatusCode { get; set; }
+
+    // Response stream for binary writes
+    public Stream OutputStream { get; }
+
+    // Write text to response (sync)
+    public void Write(string text);
+
+    // Write text to response (async) — preferred
+    public Task WriteAsync(string text);
+
+    // Write binary data to response (sync)
+    public void BinaryWrite(byte[] data);
+
+    // Write binary data to response (async) — preferred
+    public Task BinaryWriteAsync(byte[] data);
+
+    // Add a response header
+    public void AddHeader(string name, string value);
+
+    // Clear response content and headers
+    public void Clear();
+
+    // [Obsolete] In Web Forms, End() threw ThreadAbortException.
+    // In Core, it sets a flag. Use 'return' instead.
+    [Obsolete("Use 'return' to exit handler.")]
+    public void End();
+
+    // Check if Response.End() was called
+    public bool IsEnded { get; }
+}
+
+

Common Usage:

+
// Set response type and status
+context.Response.ContentType = "application/json";
+context.Response.StatusCode = 200;
+
+// Write content
+context.Response.Write("{\"message\":\"success\"}");
+
+// Add header for download
+context.Response.AddHeader("Content-Disposition", 
+    "attachment; filename=\"report.pdf\"");
+
+// For file downloads, clear and write binary
+context.Response.Clear();
+context.Response.ContentType = "application/pdf";
+context.Response.BinaryWrite(fileBytes);
+
+
+

HttpHandlerServer

+

Server-side utilities: path mapping, encoding/decoding.

+
public class HttpHandlerServer
+{
+    // Map virtual path to physical file path
+    // ~/path → webroot, /path → content root
+    public string MapPath(string virtualPath);
+
+    // HTML-encode a string (prevent XSS)
+    public string HtmlEncode(string text);
+
+    // HTML-decode a string
+    public string HtmlDecode(string text);
+
+    // URL-encode a string
+    public string UrlEncode(string text);
+
+    // URL-decode a string
+    public string UrlDecode(string text);
+}
+
+

Common Usage:

+
// Get physical file path from virtual path
+var file = context.Server.MapPath("~/App_Data/users.xml");
+
+// Safe HTML output (prevent XSS)
+var safe = context.Server.HtmlEncode("<script>alert(1)</script>");
+// Result: "&lt;script&gt;alert(1)&lt;/script&gt;"
+
+// URL encoding for query strings
+var encoded = context.Server.UrlEncode("hello world");
+// Result: "hello+world"
+
+
+

Session State

+

If your handler uses session state (e.g., storing user preferences, shopping cart), mark it with the [RequiresSessionState] attribute. The framework will automatically load session before invoking your handler.

+

Enabling Session in Program.cs

+

First, configure session in your Program.cs:

+
var builder = WebApplication.CreateBuilder(args);
+
+// Add session services
+builder.Services.AddSession(options =>
+{
+    options.IdleTimeout = TimeSpan.FromMinutes(20);
+    options.Cookie.HttpOnly = true;
+    options.Cookie.IsEssential = true;
+});
+
+var app = builder.Build();
+
+// Enable session middleware
+app.UseSession();
+
+// Register handlers (after UseSession)
+app.MapHandler<ShoppingCartHandler>("/Handlers/ShoppingCart.ashx");
+
+app.Run();
+
+

Using Session in a Handler

+

Mark the handler with [RequiresSessionState]:

+
[RequiresSessionState]
+public class ShoppingCartHandler : HttpHandlerBase
+{
+    public override async Task ProcessRequestAsync(HttpHandlerContext context)
+    {
+        var action = context.Request.QueryString["action"];
+
+        if (action == "add")
+        {
+            var productId = context.Request.Form["productId"];
+            var quantity = int.Parse(context.Request.Form["quantity"] ?? "1");
+
+            // Get cart from session (returns null if not set)
+            var cart = context.Session?.GetObject<List<CartItem>>("Cart") 
+                ?? new List<CartItem>();
+
+            cart.Add(new CartItem { ProductId = productId, Quantity = quantity });
+
+            // Save cart back to session
+            context.Session?.SetObject("Cart", cart);
+
+            context.Response.ContentType = "application/json";
+            context.Response.Write("{\"status\":\"added\"}");
+        }
+        else if (action == "view")
+        {
+            var cart = context.Session?.GetObject<List<CartItem>>("Cart") 
+                ?? new List<CartItem>();
+
+            context.Response.ContentType = "application/json";
+            var json = JsonSerializer.Serialize(new { items = cart, count = cart.Count });
+            context.Response.Write(json);
+        }
+    }
+}
+
+public class CartItem
+{
+    public string ProductId { get; set; }
+    public int Quantity { get; set; }
+}
+
+
+

Warning

+

Session is cookie-based in ASP.NET Core, not in-process. If you relied on Web Forms session state server or SQL session store, you must reconfigure that separately. For now, session is volatile and lost on app restart.

+
+
+

Note

+

GetObject<T>() and SetObject<T>() are extension methods on ISession provided by BWFC. They use System.Text.Json to serialize/deserialize objects.

+
+
+

What's Not Supported

+

Some Web Forms patterns cannot be shimmed in ASP.NET Core. Here's a clear list and recommended workarounds:

+

Response.End() — ThreadAbort Pattern

+

Web Forms: +

context.Response.Write("Data");
+context.Response.End();  // Threw ThreadAbortException, halted execution
+

+

Blazor: +

context.Response.Write("Data");
+return;  // Use return instead
+

+
+

Warning

+

In Web Forms, Response.End() threw an exception to stop the handler mid-execution. ASP.NET Core has no equivalent. The HttpHandlerResponse.End() method is marked [Obsolete] and only sets a flag. You must change Response.End() to return.

+
+
+

Server.Transfer() — Server-Side Redirect

+

Not Supported. Server.Transfer() re-executes another handler in the same request without a round-trip. ASP.NET Core has no equivalent.

+

Workaround: Use Response.Redirect() or restructure as a service method:

+
// Web Forms (not supported)
+// context.Server.Transfer("/Handlers/Other.ashx?id=123");
+
+// Blazor alternative 1: Redirect (browser round-trip)
+context.Response.Redirect("/Handlers/Other.ashx?id=123");
+
+// Blazor alternative 2: Refactor as shared service
+var handler = new OtherHandler();
+await handler.ProcessRequestAsync(context);
+
+
+

Application["key"] — Global State

+

Not Supported. Application was a global dictionary shared across requests. ASP.NET Core discourages this pattern.

+

Workaround: Use dependency injection or IMemoryCache:

+
// Web Forms (not supported)
+// var count = (int)context.Application["RequestCount"];
+
+// Blazor: Use DI + singleton service
+public class StatsHandler : HttpHandlerBase
+{
+    private readonly AppStatisticsService _stats;
+
+    public StatsHandler(AppStatisticsService stats)
+    {
+        _stats = stats;
+    }
+
+    public override async Task ProcessRequestAsync(HttpHandlerContext context)
+    {
+        var count = _stats.GetRequestCount();
+        context.Response.Write(count.ToString());
+    }
+}
+
+// Register in Program.cs
+builder.Services.AddSingleton<AppStatisticsService>();
+// ...
+app.MapHandler<StatsHandler>("/api/Stats.ashx");
+
+
+

context.Cache — Web Forms Caching

+

Not Supported. Web Forms System.Web.Caching.Cache doesn't exist in Core.

+

Workaround: Use IMemoryCache:

+
// Web Forms (not supported)
+// var cached = context.Cache["key"];
+
+// Blazor: Inject IMemoryCache
+public class CachedDataHandler : HttpHandlerBase
+{
+    private readonly IMemoryCache _cache;
+
+    public CachedDataHandler(IMemoryCache cache)
+    {
+        _cache = cache;
+    }
+
+    public override async Task ProcessRequestAsync(HttpHandlerContext context)
+    {
+        if (!_cache.TryGetValue("data", out List<Data> data))
+        {
+            data = await LoadDataFromDatabase();
+            _cache.Set("data", data, TimeSpan.FromMinutes(5));
+        }
+
+        context.Response.ContentType = "application/json";
+        context.Response.Write(JsonSerializer.Serialize(data));
+    }
+}
+
+// Register in Program.cs
+builder.Services.AddMemoryCache();
+// ...
+app.MapHandler<CachedDataHandler>("/api/Data.ashx");
+
+
+

Server.Execute() — Execute Without Transfer

+

Not Supported. Similar to Server.Transfer() — there's no way to execute another handler and return to the caller.

+

Workaround: Refactor as a service or async method.

+
+

Complex Request.Files Scenarios

+

Partially Supported. The IFormFile API in Core differs from Web Forms HttpPostedFile.

+

Web Forms: +

var file = context.Request.Files["upload"];
+file.SaveAs(context.Server.MapPath("~/uploads/" + file.FileName));
+

+

Blazor: +

var file = context.Request.Files["upload"];
+var path = context.Server.MapPath("~/uploads/" + file.FileName);
+using (var stream = System.IO.File.Create(path))
+{
+    await file.CopyToAsync(stream);
+}
+

+

The logic is the same; the API is slightly different.

+
+

Interaction with AshxHandlerMiddleware

+

If your application uses the AshxHandlerMiddleware (which returns 410 Gone for old .ashx files), migrated handlers will bypass the middleware and be handled by the routing system instead.

+

Setup: +

// Program.cs
+var app = builder.Build();
+
+// Ashx middleware (returns 410 for unmigrated handlers)
+app.UseMiddleware<AshxHandlerMiddleware>();
+
+// Handler routing (takes precedence over middleware for migrated handlers)
+app.MapHandler<ProductApiHandler>("/api/Products.ashx");
+
+// Other middleware...
+app.Run();
+

+

How it works: +1. Request arrives for /api/Products.ashx +2. AshxHandlerMiddleware runs first, checks: "Is there a handler registered for this path?" +3. Yes → middleware passes through (short-circuits) +4. ASP.NET Core routing finds the MapHandler<T>() endpoint and executes it +5. If no handler found, middleware returns 410 Gone (old handlers are gone)

+

This setup lets you migrate handlers incrementally: old ones return 410; new ones work normally.

+
+

Dependency Injection in Handlers

+

Handlers support constructor injection. Register your services in Program.cs and they'll be available:

+
public class UserApiHandler : HttpHandlerBase
+{
+    private readonly UserRepository _repo;
+
+    public UserApiHandler(UserRepository repo)
+    {
+        _repo = repo;
+    }
+
+    public override async Task ProcessRequestAsync(HttpHandlerContext context)
+    {
+        var users = await _repo.GetAllAsync();
+        context.Response.ContentType = "application/json";
+        context.Response.Write(JsonSerializer.Serialize(users));
+    }
+}
+
+// Program.cs
+builder.Services.AddScoped<UserRepository>();
+// ...
+app.MapHandler<UserApiHandler>("/api/users.ashx");
+
+
+

Testing Handlers

+

Use TestServer to test handlers in isolation:

+
// xUnit test
+[Fact]
+public async Task GetProducts_ReturnsJson()
+{
+    var builder = new WebHostBuilder()
+        .ConfigureServices(services =>
+        {
+            services.AddBlazorWebFormsComponents();
+        })
+        .Configure(app =>
+        {
+            app.MapHandler<ProductApiHandler>("/api/Products.ashx");
+        });
+
+    using (var server = new TestServer(builder))
+    using (var client = server.CreateClient())
+    {
+        var response = await client.GetAsync("/api/Products.ashx?action=list");
+
+        Assert.True(response.IsSuccessStatusCode);
+        Assert.Contains("application/json", response.Content.Headers.ContentType.ToString());
+
+        var content = await response.Content.ReadAsStringAsync();
+        Assert.Contains("Widget", content);
+    }
+}
+
+
+

Common Patterns and Examples

+

Example: JSON POST Handler with Form Data

+
public class FormSubmitHandler : HttpHandlerBase
+{
+    private readonly FormRepository _repo;
+
+    public FormSubmitHandler(FormRepository repo)
+    {
+        _repo = repo;
+    }
+
+    public override async Task ProcessRequestAsync(HttpHandlerContext context)
+    {
+        if (context.Request.HttpMethod != "POST")
+        {
+            context.Response.StatusCode = 405;
+            context.Response.Write("{\"error\":\"Method not allowed\"}");
+            return;
+        }
+
+        var name = context.Request.Form["name"];
+        var email = context.Request.Form["email"];
+
+        if (string.IsNullOrEmpty(name) || string.IsNullOrEmpty(email))
+        {
+            context.Response.StatusCode = 400;
+            context.Response.ContentType = "application/json";
+            context.Response.Write("{\"error\":\"Missing fields\"}");
+            return;
+        }
+
+        await _repo.SaveFormAsync(new { name, email });
+
+        context.Response.ContentType = "application/json";
+        context.Response.Write("{\"status\":\"submitted\"}");
+    }
+}
+
+// Program.cs
+app.MapHandler<FormSubmitHandler>("/api/Submit.ashx");
+
+

Example: Authenticated Handler (GET only)

+
public class ExportHandler : HttpHandlerBase
+{
+    public override async Task ProcessRequestAsync(HttpHandlerContext context)
+    {
+        if (!context.User.Identity?.IsAuthenticated ?? true)
+        {
+            context.Response.StatusCode = 403;
+            context.Response.Write("Unauthorized");
+            return;
+        }
+
+        var data = await GetExportDataAsync();
+        var csv = ConvertToCSV(data);
+
+        context.Response.ContentType = "text/csv";
+        context.Response.AddHeader("Content-Disposition", 
+            "attachment; filename=\"export.csv\"");
+        context.Response.Write(csv);
+    }
+}
+
+// Program.cs
+app.MapHandler<ExportHandler>("/secure/export.ashx")
+   .RequireAuthorization();
+
+
+

Troubleshooting

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProblemSolution
Handler returns 404Verify the route pattern in MapHandler<T>() matches the request URL. Check that the MapHandler call exists in Program.cs.
Session state is nullAdd [RequiresSessionState] attribute. Ensure app.UseSession() is called in Program.cs.
"Response.End() was called" warningRemove Response.End() and use return instead.
Dependency injection failsRegister services in Program.cs before builder.Build().
File upload not workingCheck content type is multipart/form-data. Use context.Request.Files["fieldName"].
CORS blockedUse .RequireCors() on the handler route. Ensure CORS policy is registered.
Old handler returns 410This is correct — old .ashx files should return 410 until migrated. Use AshxHandlerMiddleware for this.
+
+

Summary

+

Migrating .ashx handlers to Blazor with HttpHandlerBase is straightforward:

+
    +
  • 6 mechanical changes per handler (shown in Quick Start)
    • +
  • Familiar API surface — context.Request, context.Response, context.Server work as in Web Forms
    • +
  • Modern routing — Use MapHandler<T>() in Program.cs for explicit route registration
    • +
  • DI support — Inject services via constructor
    • +
  • Session state — Mark with [RequiresSessionState], configure in Program.cs
    • +
  • What's unsupported — Response.End(), Server.Transfer(), global state — listed with workarounds
    • +
+

Your handler logic stays nearly identical. You're just updating the registration and removing obsolete patterns.

+

For questions or edge cases, refer to the API Reference section or consult the BlazorWebFormsComponents repository.

+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/NET-Standard/index.html b/site/Migration/NET-Standard/index.html new file mode 100644 index 000000000..954037e5b --- /dev/null +++ b/site/Migration/NET-Standard/index.html @@ -0,0 +1,4589 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .NET Standard to the Rescue - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

.NET Standard to the Rescue

+ +

.NET Standard is the definition of a contract, a series of APIs, that all .NET frameworks must implement to be considered a .NET framework. .NET Framework, .NET Core, Xamarin, and Mono all implement various .NET Standard versions (or specifications) and this now becomes a vehicle for you to build your class libraries to be re-usable across various version of .NET.

+

.NET Standard specifications are managed in the open with definitions fore APIs and frameworks that .NET can be used with.

+

Class libraries can be built and target different version specifications of .NET Standard. You can target ANY version of .NET Standard and gain compatibility across .NET Framework and .NET Core, but we recommend you target at least .NET Standard 2.0

+

.NET Standard Version Table

+

Implications

+

For your existing Web Forms applications, unless you are executing unsafe code or p-invoking methods, you should be able to migrate much of your application's business logic to a .NET Standard targeting class library. This has several benefits:

+
    +
  1. You can migrate your business logic to the .NET Standard class library project, reference that project, and continue to use that logic in your ASP.NET Web Forms application.
    2. +
  2. Your new .NET Standard class library project can be DIRECTLY referenced by your migrated ASP.NET Core / Server-side Blazor application
    3. +
  3. Your business logic code is now isolated from your presentation code, and should be more testable. Write some unit tests to verify that your business logic is behaving properly.
    4. +
  4. If you'd like to write a mobile application to work with your web application, you can re-use your .NET Standard project with the Xamarin frameworks.
    5. +
+

API Portability

+

Portability is not guaranteed when you migrate business logic to .NET Standard. APIs have been changed or even removed in some cases. You should test your libraries and application for portability and take direction for possible migration paths using the official .NET Portability Analyzer.

+

Sample 1: Update an existing class library

+

The first sample demonstrates updating a simple class library to .NET Standard. In this model, we're assuming that you already have your business logic code properly separated from your user-interface and managed inside a class-library project that targets .NET Framework 4.5. You can find it in the samples/netstandard-1 folder in the repository.

+

Sample 2: Refactoring Business Logic

+

The second sample shows how to take an existing ASP.NET application and refactor our some business logic as a .NET Standard project. You can find the source and directions for this sample in the samples/netstandard-2 (coming soon) folder.

+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/Strategies/index.html b/site/Migration/Strategies/index.html new file mode 100644 index 000000000..d7b02d877 --- /dev/null +++ b/site/Migration/Strategies/index.html @@ -0,0 +1,4808 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Migration Strategies - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Migration Strategies

+ +

Migration from ASP.NET Web Forms to Blazor is not simple and this repository attempts to make it easier for developers to reuse as much of their Web Forms application as possible. The two technologies are 'concept compatible', but run on different implementations of the .NET runtime (.NET Framework vs. .NET Core / .NET 5+)

+

We, the maintainers of this project, believe that with a little ingenuity the markup from a Web Forms application can be copied over with minimal changes and function similarly to its original purpose. We believe that well formatted and maintained code in Web Forms should be easily migrated. Applications that are a significant mix of C# and markup will have a more difficult time going through this process.

+

Readiness Planning

+

Migrating an application to Blazor is not a trivial process and it would be great to have some indication ahead of time how much work is needed and what steps you need to take to prepare to migrate. Check our migration readiness document to help determine how much work will be needed for your application to begin the process.

+

Known Required Changes

+

There are several changes that are going to need to be made to the markup in your ASPX and ASCX files in order to get them working. Some of these are obvious changes, and some are considerations necessary for the razor templating and Blazor rendering engine.

+

Visual Basic converted to C

+

Blazor uses razor templates which only support the C# language. All Visual Basic in the markup will need to be converted to C#.

+

Bee-sting notation <% %> needs to be converted to @() notation

+

ASP.NET famously wrapped all .NET code in <% %>. Starting with ASP.NET MVC and razor templates, all C# code is wrapped in @() syntax.

+

_Imports files needed

+

In order to match some of the syntax previously available in Web Forms markup, a series of using static statements are necessary to allow the appropriate shims to work with your markup. You can find our sample of the _Imports.razor file here: INSERT LINK

+

User Controls (ASCX files) need to be converted to components

+

Components are the building blocks for Blazor, just as controls were in Web Forms. If you have user controls in your application, you will need to convert those to components. See the UserControl strategy below for more details.

+

MasterPages are no more

+

The concept of a MasterPage does not exist in Blazor. Instead, your ASPX pages will be loaded inside of a host page. You can compose a razor component that hosts other converted ASPX pages but your pages cannot dictate their parent container. See the MasterPage strategy below for more details.

+

Page Directive Changes

+

<%#: DataBinding expressions require update

+

Databinding expressions in Web Forms let you evaluate the content of the elements and format them appropriately for presentation. For editor controls, it also allows you to setup a 2-way binding so that you can receive values entered into the same variable bound to the control.

+

In Blazor, for repeater-style components, the simplest solution is to just format the variable using context, Item, and formatting:

+
@Item.ShipDate.ToString("D")
+
+

For editor components, simply @bind the variable to the component. This will give you two-way data-binding and the ability to handle changes in the editor component AS it changes.

+
<input type="text" name="foo" @bind="bar" />
+
+

More details about DataBinding and using the DataBinder utility object are available in the DataBinder docs.

+

No Namespaces, No Tag-Prefixes

+

Namespaces and tag-prefixes are gone. You can do a Find and Replace on asp: and remove those from your markup.

+

Redirect Color to WebColor

+

This change should NOT require any coding modifications. In Web Forms, you could refer to System.Drawing.Color objects when setting BackColor, BorderColor, and ForeColor to name a few properties. You could ALSO freely use HTML hex-color notation freely in these fields. +The System.Drawing.Color object does not have a converter that allows you to convert between these two formats, so we wrapped the object and made BlazorWebFormsComponents.WebColor that performs the same task and allows the interchange of System.Drawing.Color object with HTML hex notation.

+

Strategies

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/ThemesAndSkins/index.html b/site/Migration/ThemesAndSkins/index.html new file mode 100644 index 000000000..55aa7e477 --- /dev/null +++ b/site/Migration/ThemesAndSkins/index.html @@ -0,0 +1,6334 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Themes and Skins - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Themes and Skins Migration Strategy

+

ASP.NET Web Forms Themes and Skins provided a centralized way to control the visual appearance of server controls across an entire application. Blazor has no built-in equivalent, but several Blazor-native approaches can achieve the same goals. This document explains the original Web Forms features, evaluates Blazor alternatives, and recommends a migration path.

+
+

Current Status — PoC Implemented (M10)

+

The theming/skinning system is now implemented as a proof-of-concept. SkinID (typed as string) and EnableTheming (typed as bool, defaults to true) are active [Parameter] properties on BaseWebFormsComponent — they are not [Obsolete]. The ThemeProvider component, ThemeConfiguration, and ControlSkin classes are live in the BlazorWebFormsComponents.Theming namespace. See the PoC Decisions section below for design choices.

+
+
+

What Are Web Forms Themes and Skins?

+

Themes

+

A Theme is a named collection of CSS files, skin files (.skin), and images stored in a well-known folder structure:

+
App_Themes/
+└── Professional/
+    ├── styles.css
+    ├── controls.skin
+    └── Images/
+        └── logo.png
+
+

Themes are applied in three ways:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodScopeExample
web.configApplication-wide<pages theme="Professional" />
@Page directiveSingle page<%@ Page Theme="Professional" %>
ProgrammaticDynamicPage.Theme = "Professional" in Page_PreInit
+

Themes have two modes that control precedence:

+
    +
  • Theme property — the theme overrides control property settings (theme wins over markup)
    • +
  • StyleSheetTheme property — the theme acts as defaults (markup wins over theme)
    • +
+

This override-vs-default distinction is critical for any migration approach.

+

Skins (.skin Files)

+

A Skin file is an XML-like file containing ASP.NET server control declarations with appearance property values — but no ID attribute and no behavioral properties:

+
<!-- Default skin — applies to ALL Button instances -->
+<asp:Button runat="server"
+    BackColor="#C04000"
+    BorderColor="Maroon"
+    Font-Names="Tahoma"
+    Font-Size="10pt" />
+
+<!-- Named skin — applies only when SkinID="action" -->
+<asp:Button runat="server" SkinID="action"
+    BackColor="Navy"
+    ForeColor="White"
+    Font-Bold="True" />
+
+

Key rules:

+
    +
  • Default skins (no SkinID) apply to every instance of that control type automatically
    • +
  • Named skins (SkinID="action") apply only to controls with a matching SkinID property
    • +
  • Only one default skin per control type is allowed
    • +
  • Only appearance properties belong in skins (colors, fonts, borders — not Text, CommandName, etc.)
    • +
+

SkinID Property

+

Every Web Forms control inherits SkinID from System.Web.UI.Control:

+
<!-- Uses the default Button skin -->
+<asp:Button ID="btnCancel" runat="server" Text="Cancel" />
+
+<!-- Uses the "action" named skin -->
+<asp:Button ID="btnSave" runat="server" Text="Save" SkinID="action" />
+
+
+

Implemented

+

SkinID is correctly typed as string on BaseWebFormsComponent and defaults to "" (empty string), which selects the default skin. Set SkinID="action" to select a named skin — just like Web Forms.

+
+
+

Blazor CSS Capabilities

+

Before evaluating approaches, here are the Blazor features available as building blocks:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureDescription
CSS Isolation{Component}.razor.css files with auto-scoped selectors via b-{hash} attributes
::deepPseudo-element for styling child component markup from a parent's scoped CSS
CSS Custom PropertiesNative CSS variables (var(--color-primary)) for theming
CascadingValue / CascadingParameterPass values down the component tree without explicit parameters
DI ServicesInject configuration objects via dependency injection
RCL BundlingComponent library CSS bundled as {PackageId}.bundle.scp.css
+
+

Approach 1: CSS Custom Properties (Variables)

+

Define theme variables at the root or page level; components reference them with var().

+

How It Works

+

Define the theme (CSS file or <style> block):

+
/* themes/professional.css */
+:root {
+    --button-bg: #C04000;
+    --button-border: Maroon;
+    --button-font: "Tahoma", sans-serif;
+    --button-font-size: 10pt;
+
+    --button-action-bg: Navy;
+    --button-action-fg: White;
+    --button-action-font-weight: bold;
+}
+
+

Component CSS uses the variables:

+
/* Button.razor.css */
+button {
+    background-color: var(--button-bg, #ddd);
+    border-color: var(--button-border, #ccc);
+    font-family: var(--button-font, inherit);
+    font-size: var(--button-font-size, inherit);
+}
+
+

SkinID support via CSS classes:

+
/* Named skin: action */
+button.skin-action {
+    background-color: var(--button-action-bg, Navy);
+    color: var(--button-action-fg, White);
+    font-weight: var(--button-action-font-weight, bold);
+}
+
+
<!-- Component applies SkinID as a CSS class -->
+<Button Text="Save" SkinID="action" />
+<!-- Renders: <button class="skin-action">Save</button> -->
+
+

Theme switching — swap the CSS file:

+
<!-- In App.razor or a layout -->
+<link href="themes/@currentTheme.css" rel="stylesheet" />
+
+

Theme vs StyleSheetTheme Semantics

+ + + + + + + + + + + + + + + + + +
ModeCSS Approach
Theme (override)Variables defined with higher specificity or !important
StyleSheetTheme (default)Variables defined on :root with normal specificity; inline styles from markup win naturally
+

CSS custom properties with var(--prop, fallback) already behave like StyleSheetTheme — an inline style attribute set in markup wins over the variable. Theme (override) semantics are harder; they require !important or higher-specificity selectors, which is fragile.

+

Strengths

+
    +
  • ✅ Pure CSS — no C# runtime cost
    • +
  • ✅ Theme switching is instant (swap a stylesheet)
    • +
  • ✅ Browser DevTools support for live editing
    • +
  • ✅ Works with CSS isolation and ::deep
    • +
  • ✅ Incrementally adoptable — add variables one component at a time
    • +
+

Weaknesses

+
    +
  • ❌ Only works for CSS-expressible properties (colors, fonts, borders)
    • +
  • ❌ Cannot set non-CSS properties (Text, Width as an HTML attribute, Visible)
    • +
  • ❌ Theme override semantics require !important hacks
    • +
  • ❌ SkinID → CSS class mapping must be built into each component
    • +
  • ❌ No compile-time validation of variable names
    • +
+
+

Approach 2: CascadingValue ThemeProvider

+

A wrapper component provides default property values via CascadingParameter.

+

How It Works

+

Define a theme model (actual implementation):

+
// BlazorWebFormsComponents.Theming.ThemeConfiguration
+public class ThemeConfiguration
+{
+    public void AddSkin(string controlTypeName, ControlSkin skin, string skinId = null);
+    public ControlSkin GetSkin(string controlTypeName, string skinId = null);
+    public bool HasSkins(string controlTypeName);
+}
+
+// BlazorWebFormsComponents.Theming.ControlSkin
+public class ControlSkin
+{
+    public WebColor BackColor { get; set; }
+    public WebColor ForeColor { get; set; }
+    public WebColor BorderColor { get; set; }
+    public BorderStyle? BorderStyle { get; set; }
+    public Unit? BorderWidth { get; set; }
+    public string CssClass { get; set; }
+    public Unit? Height { get; set; }
+    public Unit? Width { get; set; }
+    public FontInfo Font { get; set; }
+    public string ToolTip { get; set; }
+}
+
+

The ThemeProvider component (actual implementation):

+
<!-- ThemeProvider.razor (in BlazorWebFormsComponents.Theming) -->
+<CascadingValue Value="Theme">
+    @ChildContent
+</CascadingValue>
+
+@code {
+    [Parameter] public ThemeConfiguration Theme { get; set; }
+    [Parameter] public RenderFragment ChildContent { get; set; }
+}
+
+

Wrap your app or page:

+
<ThemeProvider Theme="@professionalTheme">
+    <Router AppAssembly="@typeof(App).Assembly">
+        <!-- ... -->
+    </Router>
+</ThemeProvider>
+
+@code {
+    private ThemeConfiguration professionalTheme = new ThemeConfiguration();
+
+    protected override void OnInitialized()
+    {
+        professionalTheme.AddSkin("Button", new ControlSkin
+        {
+            BackColor = WebColor.Blue,
+            ForeColor = WebColor.White
+        });
+    }
+}
+
+

Components read from the cascaded theme (actual implementation in BaseStyledComponent):

+
// Inside BaseStyledComponent
+[CascadingParameter]
+public ThemeConfiguration Theme { get; set; }
+
+protected override void OnParametersSet()
+{
+    base.OnParametersSet();
+
+    if (!EnableTheming || Theme == null) return;
+
+    var skin = Theme.GetSkin(GetType().Name, SkinID);
+    if (skin == null) return;
+
+    ApplySkin(skin);
+}
+
+private void ApplySkin(ControlSkin skin)
+{
+    // StyleSheetTheme semantics: apply only if property not explicitly set
+    if (BackColor == default && skin.BackColor != default)
+        BackColor = skin.BackColor;
+
+    if (ForeColor == default && skin.ForeColor != default)
+        ForeColor = skin.ForeColor;
+
+    // ... repeat for other appearance properties
+}
+
+

Theme vs StyleSheetTheme Semantics

+
// The current PoC implements StyleSheetTheme semantics only:
+// theme sets defaults, but explicit component values take precedence.
+// Theme (override) mode is deferred to M11.
+
+// In BaseStyledComponent.ApplySkin:
+// Only apply if the component property is at its default value
+if (BackColor == default && skin.BackColor != default)
+    BackColor = skin.BackColor;
+
+

The current implementation uses StyleSheetTheme semantics exclusively — the theme sets defaults, and any value explicitly set on the component takes precedence. Theme (override) mode, where the theme always wins, is deferred to M11.

+

SkinID Support

+
<!-- Default skin applies automatically -->
+<Button Text="Cancel" />
+
+<!-- Named skin "action" applies -->
+<Button Text="Save" SkinID="action" />
+
+

Both work identically to Web Forms — the base class resolves the correct skin entry.

+

Strengths

+
    +
  • ✅ Faithful to Web Forms semantics — supports both Theme and StyleSheetTheme modes
    • +
  • ✅ SkinID works exactly like Web Forms
    • +
  • ✅ Can set any property, not just CSS-related ones
    • +
  • ✅ Compile-time type safety on the theme model
    • +
  • ✅ Theme data could be loaded from .skin-like configuration files
    • +
  • ✅ Single point of change in BaseWebFormsComponent benefits all 50+ components
    • +
+

Weaknesses

+
    +
  • ❌ Requires changes to BaseWebFormsComponent (touches every component)
    • +
  • ❌ Runtime cost — theme resolution on every OnParametersSet
    • +
  • ❌ Not a standard Blazor pattern — new contributors must learn it
    • +
  • ❌ Theme switching requires re-render of the entire component tree
    • +
+
+

Approach 3: Generated CSS Isolation Files

+

Pre-generate .razor.css files for each component from skin definitions. Closest to Jeff's initial idea.

+

How It Works

+

Source: a skin definition file (JSON, YAML, or .skin):

+
{
+    "theme": "Professional",
+    "skins": {
+        "Button": {
+            "default": {
+                "background-color": "#C04000",
+                "border-color": "Maroon",
+                "font-family": "Tahoma",
+                "font-size": "10pt"
+            },
+            "action": {
+                "background-color": "Navy",
+                "color": "White",
+                "font-weight": "bold"
+            }
+        },
+        "TextBox": {
+            "default": {
+                "border": "1px solid #999",
+                "padding": "4px"
+            }
+        }
+    }
+}
+
+

Build-time tool generates scoped CSS:

+
/* Button.razor.css (generated) */
+button {
+    background-color: #C04000;
+    border-color: Maroon;
+    font-family: "Tahoma", sans-serif;
+    font-size: 10pt;
+}
+
+button[data-skinid="action"] {
+    background-color: Navy;
+    color: White;
+    font-weight: bold;
+}
+
+

SkinID rendered as a data- attribute:

+
<!-- Button.razor (modified) -->
+<button data-skinid="@SkinID" class="@CssClass" style="@Style">
+    @Text
+</button>
+
+

Theme Switching

+

Generate separate CSS bundles per theme. Switch by loading a different bundle:

+
<link href="_content/BlazorWebFormsComponents/themes/professional.css" rel="stylesheet" />
+
+

Theme vs StyleSheetTheme Semantics

+ + + + + + + + + + + + + + + + + +
ModeGenerated CSS Approach
StyleSheetTheme (default)Generated CSS uses low specificity; inline style attributes from markup override
Theme (override)Generated CSS uses !important or high-specificity selectors
+

Strengths

+
    +
  • ✅ Aligns with Jeff's initial idea
    • +
  • ✅ Pure CSS output — no runtime cost
    • +
  • ✅ Leverages Blazor's built-in CSS isolation
    • +
  • ✅ Theme files can be authored by designers without C# knowledge
    • +
  • ✅ Build-time validation of skin definitions
    • +
+

Weaknesses

+
    +
  • ❌ Requires a build-time code generation tool (MSBuild task or Source Generator)
    • +
  • ❌ Only works for CSS-expressible properties
    • +
  • ❌ Cannot set non-CSS properties (Visible, Width as attribute, etc.)
    • +
  • ❌ Generated CSS fights with CSS isolation scoping (b-{hash} attributes)
    • +
  • ❌ Theme override semantics are fragile (!important)
    • +
  • ❌ Significant tooling investment for a migration-only feature
    • +
+
+

Approach 4: Dictionary-Based Configuration via DI

+

A ThemeConfiguration service registered in DI holds property defaults per control type, keyed by optional SkinID. (Note: This section shows a hypothetical DI-based variant — not the actual implementation. See Approach 2 for the implemented API.)

+

How It Works

+

Define the configuration service:

+
public class ThemeConfiguration
+{
+    public string ThemeName { get; set; } = "Default";
+    public ThemeMode Mode { get; set; } = ThemeMode.StyleSheetTheme;
+
+    private readonly Dictionary<string, ControlSkinDefaults> _skins = new();
+
+    /// <summary>
+    /// Register a default skin for a control type.
+    /// </summary>
+    public void AddDefaultSkin<TControl>(ControlSkinDefaults defaults)
+        where TControl : BaseWebFormsComponent
+    {
+        _skins[typeof(TControl).Name] = defaults;
+    }
+
+    /// <summary>
+    /// Register a named skin for a control type.
+    /// </summary>
+    public void AddNamedSkin<TControl>(string skinId, ControlSkinDefaults defaults)
+        where TControl : BaseWebFormsComponent
+    {
+        _skins[$"{typeof(TControl).Name}:{skinId}"] = defaults;
+    }
+
+    public ControlSkinDefaults? GetSkin(Type controlType, string? skinId = null)
+    {
+        if (!string.IsNullOrEmpty(skinId) &&
+            _skins.TryGetValue($"{controlType.Name}:{skinId}", out var named))
+            return named;
+
+        _skins.TryGetValue(controlType.Name, out var def);
+        return def;
+    }
+}
+
+

Register in DI:

+
// Program.cs
+builder.Services.AddSingleton<ThemeConfiguration>(sp =>
+{
+    var theme = new ThemeConfiguration { ThemeName = "Professional" };
+
+    theme.AddDefaultSkin<Button>(new ControlSkinDefaults
+    {
+        BackColor = WebColor.FromName("Maroon"),
+        FontFamily = "Tahoma",
+        FontSize = "10pt"
+    });
+
+    theme.AddNamedSkin<Button>("action", new ControlSkinDefaults
+    {
+        BackColor = WebColor.FromName("Navy"),
+        ForeColor = WebColor.FromName("White"),
+        FontBold = true
+    });
+
+    return theme;
+});
+
+

Components inject the service:

+
// BaseWebFormsComponent.cs
+[Inject]
+protected ThemeConfiguration? ThemeConfig { get; set; }
+
+protected override void OnParametersSet()
+{
+    if (ThemeConfig != null)
+    {
+        var skin = ThemeConfig.GetSkin(GetType(), SkinID);
+        if (skin != null) ApplySkin(skin, ThemeConfig.Mode);
+    }
+}
+
+

Theme Switching

+

Swap the DI registration or use a scoped service:

+
builder.Services.AddScoped<ThemeConfiguration>(sp =>
+    ThemeLoader.LoadFromJson("wwwroot/themes/professional.json"));
+
+

Strengths

+
    +
  • ✅ Standard DI pattern — familiar to Blazor developers
    • +
  • ✅ Supports both Theme and StyleSheetTheme semantics
    • +
  • ✅ SkinID works like Web Forms
    • +
  • ✅ Can set any property (not limited to CSS)
    • +
  • ✅ Theme data can be loaded from JSON/XML files at startup
    • +
  • ✅ No component tree re-render on theme switch (if scoped per-circuit)
    • +
+

Weaknesses

+
    +
  • ❌ Service injection in base component may surprise library consumers
    • +
  • ❌ Configuration is imperative (code), not declarative (markup)
    • +
  • ❌ Requires changes to BaseWebFormsComponent
    • +
  • ❌ No cascading scope — the theme applies globally per DI scope
    • +
  • ❌ Cannot easily scope a theme to a subtree of components (unlike CascadingValue)
    • +
+
+

Approach 5: Hybrid — CSS Variables + CascadingParameter

+

Use CSS custom properties for visual styles (colors, fonts, borders) and CascadingParameter for non-CSS properties.

+

How It Works

+

CSS variables handle the visual layer:

+
/* themes/professional.css */
+:root {
+    --bwfc-button-bg: #C04000;
+    --bwfc-button-border: Maroon;
+    --bwfc-button-font: "Tahoma", sans-serif;
+}
+
+

CascadingParameter handles non-CSS properties:

+
public class ThemeDefaults
+{
+    public ThemeMode Mode { get; set; } = ThemeMode.StyleSheetTheme;
+    public Dictionary<(Type, string?), NonCssDefaults> Defaults { get; } = new();
+}
+
+public class NonCssDefaults
+{
+    public string? Width { get; set; }   // HTML attribute, not CSS
+    public bool? Visible { get; set; }
+    public string? ToolTip { get; set; }
+}
+
+

Components use both:

+
/* Button.razor.css */
+button {
+    background-color: var(--bwfc-button-bg);
+    border-color: var(--bwfc-button-border);
+    font-family: var(--bwfc-button-font);
+}
+
+
// Button.razor.cs
+[CascadingParameter(Name = "ThemeDefaults")]
+private ThemeDefaults? ThemeDefaults { get; set; }
+
+protected override void OnParametersSet()
+{
+    // CSS properties handled by CSS variables — no C# needed
+    // Only non-CSS properties resolved here
+    if (ThemeDefaults?.Defaults.TryGetValue(
+            (GetType(), SkinID), out var defaults) == true)
+    {
+        if (Width == null && defaults.Width != null)
+            Width = defaults.Width;
+    }
+}
+
+

SkinID maps to CSS class + cascading lookup:

+
button.skin-action {
+    background-color: var(--bwfc-button-action-bg, Navy);
+    color: var(--bwfc-button-action-fg, White);
+}
+
+

Strengths

+
    +
  • ✅ Best of both worlds — CSS for visual, C# for structural
    • +
  • ✅ Theme switching is fast (CSS swap for visuals, no full re-render)
    • +
  • ✅ Clean separation of concerns
    • +
  • ✅ Incrementally adoptable
    • +
+

Weaknesses

+
    +
  • ❌ Two systems to learn and maintain
    • +
  • ❌ Splitting properties between CSS and C# creates confusion
    • +
  • ❌ SkinID must be handled in both CSS and C# code
    • +
  • ❌ Most complex implementation of all approaches
    • +
+
+

Comparison Matrix

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CriteriaCSS VariablesCascadingValueGenerated CSSDI ServiceHybrid
Web Forms SkinID fidelity⚠️ Partial✅ Full⚠️ Partial✅ Full✅ Full
Theme mode (override)❌ Fragile✅ Yes❌ Fragile✅ Yes⚠️ Partial
StyleSheetTheme mode (default)✅ Natural✅ Yes✅ Natural✅ Yes✅ Yes
Non-CSS properties❌ No✅ Yes❌ No✅ Yes✅ Yes
Runtime performance✅ Zero⚠️ Per-render✅ Zero⚠️ Per-render⚠️ Mixed
Incremental adoption✅ Easy⚠️ Medium❌ Hard⚠️ Medium⚠️ Medium
Tooling investment✅ None✅ Low❌ High✅ Low⚠️ Medium
Scoped to subtree✅ CSS scope✅ Cascading✅ CSS scope❌ Global DI✅ Mixed
Blazor-idiomatic✅ Yes✅ Yes⚠️ Somewhat✅ Yes⚠️ Complex
+
+

Implemented Approach: CascadingValue ThemeProvider (Approach 2)

+

The CascadingValue ThemeProvider is the selected and implemented approach. It was chosen for the following reasons:

+

Rationale

+
    +
  1. +

    Highest Web Forms fidelity. It is the only approach that can faithfully model both Theme (override) and StyleSheetTheme (default) semantics, plus SkinID selection, using the same mental model as the original. The PoC defaults to StyleSheetTheme semantics (theme sets defaults, explicit values override).

    +
    2. +
  2. +

    Works for all property types. Unlike CSS-only approaches, it sets BackColor, ForeColor, Width, ToolTip, CssClass, Font, and other appearance properties — matching what .skin files actually do. The ControlSkin class mirrors the properties on BaseStyledComponent.

    +
    3. +
  3. +

    Single point of change. The theme resolution logic lives in BaseStyledComponent.OnParametersSet. Once implemented there, all 50+ components in the library inherit the behavior automatically. No per-component work required.

    +
    4. +
  4. +

    Familiar Blazor pattern. CascadingValue/CascadingParameter is a well-documented, first-class Blazor feature. Developers already encounter it with EditContext, CascadingAuthenticationState, and the library's own TableItemStyle cascading.

    +
    5. +
  5. +

    Scoped application. Unlike DI (which is global), a CascadingValue can be scoped to a page or section — matching how Web Forms allows StyleSheetTheme on a per-page basis via the @Page directive.

    +
    6. +
  6. +

    Incrementally adoptable. The ThemeProvider component and base class changes ship without requiring any existing consumer to change their code. Themes are opt-in: if no ThemeProvider wraps the component tree, behavior is unchanged.

    +
    7. +
+

Implementation Roadmap

+

Phase 1 — Foundation (✅ Complete — M10 PoC)

+
    +
  • ~~Fix SkinID type from bool to string on BaseWebFormsComponent~~ ✅ Done
    • +
  • ~~Remove [Obsolete] from SkinID and EnableTheming~~ ✅ Done
    • +
  • ~~Define ControlSkin and ThemeConfiguration~~ ✅ Done (in BlazorWebFormsComponents.Theming namespace)
    • +
  • ~~Create ThemeProvider cascading wrapper component~~ ✅ Done
    • +
  • ~~Add theme resolution to BaseStyledComponent.OnParametersSet~~ ✅ Done
    • +
+

Phase 2 — Full Implementation (Deferred to M11)

+
    +
  • .skin file parser (reading actual .skin files)
    • +
  • StyleSheetTheme vs Theme priority distinction
    • +
  • Runtime theme switching
    • +
  • Sub-component style theming (HeaderStyle, RowStyle, etc.)
    • +
  • Container-level EnableTheming propagation to children
    • +
  • JSON theme format as alternative input
    • +
+

Phase 3 — Documentation & Samples

+
    +
  • Sample page demonstrating theme switching
    • +
  • Migration guide addendum showing before/after for themed Web Forms apps
    • +
+

Complementary CSS Variables

+

While the CascadingValue approach is primary, nothing prevents developers from also using CSS custom properties for pure-CSS theming on top. The two are complementary:

+
<!-- CascadingValue for property defaults -->
+<ThemeProvider Theme="@myTheme">
+    <!-- CSS variables for visual layer -->
+    <div style="--bwfc-primary: Navy; --bwfc-accent: Gold;">
+        <Button Text="Themed" SkinID="action" />
+    </div>
+</ThemeProvider>
+
+
+

Migration Example: Before and After

+

Before — Web Forms with Theme

+

App_Themes/Corporate/buttons.skin: +

<asp:Button runat="server"
+    BackColor="#336699"
+    ForeColor="White"
+    Font-Names="Segoe UI"
+    Font-Size="9pt"
+    BorderStyle="None" />
+
+<asp:Button runat="server" SkinID="danger"
+    BackColor="#CC3333"
+    ForeColor="White"
+    Font-Bold="True" />
+

+

web.config: +

<pages theme="Corporate" />
+

+

Products.aspx: +

<%@ Page Title="Products" %>
+<asp:Button ID="btnSave" runat="server" Text="Save" />
+<asp:Button ID="btnDelete" runat="server" Text="Delete" SkinID="danger" />
+

+

After — Blazor with ThemeProvider

+

CorporateTheme.cs: +

using BlazorWebFormsComponents.Theming;
+
+public static class CorporateTheme
+{
+    public static ThemeConfiguration Create()
+    {
+        var theme = new ThemeConfiguration();
+
+        // Default skin — applies to ALL Button instances
+        theme.AddSkin("Button", new ControlSkin
+        {
+            BackColor = WebColor.FromHtml("#336699"),
+            ForeColor = WebColor.FromName("White"),
+            Font = new FontInfo { Name = "Segoe UI", Size = new FontUnit("9pt") },
+        });
+
+        // Named skin — applies only when SkinID="danger"
+        theme.AddSkin("Button", new ControlSkin
+        {
+            BackColor = WebColor.FromHtml("#CC3333"),
+            ForeColor = WebColor.FromName("White"),
+            Font = new FontInfo { Bold = true }
+        }, "danger");
+
+        return theme;
+    }
+}
+

+

App.razor (or layout): +

@using BlazorWebFormsComponents.Theming
+
+<ThemeProvider Theme="@CorporateTheme.Create()">
+    <Router AppAssembly="@typeof(App).Assembly">
+        <Found Context="routeData">
+            <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
+        </Found>
+    </Router>
+</ThemeProvider>
+

+

Products.razor: +

@page "/products"
+
+<Button ID="btnSave" Text="Save" />
+<Button ID="btnDelete" Text="Delete" SkinID="danger" />
+

+

The markup is nearly identical. The theme is applied automatically, just like Web Forms.

+
+

PoC Decisions

+

The following design decisions were made during the M10 PoC implementation:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DecisionRationale
Default to StyleSheetTheme semanticsThe theme sets default values; any value explicitly set on a component takes precedence. This is the safer default for migration — existing markup is preserved. Theme (override) mode is deferred to M11.
Missing SkinID: log warning, don't throwWhen a component specifies SkinID="foo" but no skin named "foo" is registered, GetSkin returns null and the component renders without theme styling. This avoids breaking the app due to configuration mismatches.
Namespace: BlazorWebFormsComponents.ThemingAll theme-related types (ThemeConfiguration, ControlSkin, ThemeProvider) live in a dedicated Theming namespace to keep the root namespace clean.
ThemeConfiguration keyed by string, not TypeControl type names are stored as strings (e.g., "Button") with case-insensitive comparison. This avoids tight coupling to concrete types and simplifies the API.
ControlSkin mirrors BaseStyledComponent propertiesThe skin model uses the same property types (WebColor, Unit, FontInfo, etc.) as the component base class, ensuring type-safe assignment.
Theme resolution in BaseStyledComponent, not BaseWebFormsComponentOnly styled components can be themed — the [CascadingParameter] ThemeConfiguration Theme and ApplySkin logic live in BaseStyledComponent.
.skin file parsing deferred to M11Parsing legacy .skin files requires a dedicated parser for the pseudo-ASPX format. The PoC validates the C# configuration API first; .skin file support will layer on top in M11.
+
+

Additional Resources

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/User-Controls/index.html b/site/Migration/User-Controls/index.html new file mode 100644 index 000000000..14323aa3c --- /dev/null +++ b/site/Migration/User-Controls/index.html @@ -0,0 +1,7160 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + User Controls - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Migrating User Controls to Blazor

+

User Controls (.ascx files) are a fundamental building block in ASP.NET Web Forms applications. They provide reusable, encapsulated UI components with both markup and code-behind logic. Migrating them to Blazor is straightforward: ASCX user controls become Razor components (.razor files) with minimal structural changes.

+

Understanding User Controls

+

Web Forms User Control Structure

+

In Web Forms, a user control consists of three parts:

+
    +
  1. +

    Register Directive — Declares the control in ASPX pages: +

    <%@ Register TagPrefix="uc" TagName="PageHeader" Src="~/Controls/PageHeader.ascx" %>
+

    +
    2. +
  2. +

    Markup (.ascx file) — The HTML and Web Forms controls: +

    <%@ Control Language="C#" AutoEventWireup="true" CodeBehind="PageHeader.ascx.cs" Inherits="DepartmentPortal.Controls.PageHeader" %>
+
+<div class="page-header">
+    <h1><%: Title %></h1>
+    <p><%: Subtitle %></p>
+</div>
+

    +
    3. +
  3. +

    Code-Behind (.ascx.cs file) — Properties, events, and lifecycle: +

    public partial class PageHeader : UserControl
+{
+    public string Title { get; set; }
+    public string Subtitle { get; set; }
+
+    protected void Page_Load(object sender, EventArgs e)
+    {
+        // Initialization logic
+    }
+}
+

    +
    4. +
+

Using User Controls in ASPX Pages

+
<uc:PageHeader ID="header" runat="server" Title="Welcome" Subtitle="To Our Site" />
+
+

The developer passed properties declaratively; ASP.NET's control tree engine bound them at runtime.

+
+

Mapping to Blazor Razor Components

+

In Blazor, user controls become Razor components:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web FormsBlazorNotes
.ascx file.razor fileSingle file combines markup + code
<%@ Register %>Import in _Imports.razorNo registration needed
Public properties[Parameter] decorated propertiesDeclare parameters for parent→child communication
Page_Load eventOnInitializedAsync or OnParametersSetAsyncLifecycle hooks differ; see below
FindControl() + casting@ref or cascading parametersDirect component references or parameter passing
Data binding <%# Eval(...) %>Direct property access @item.PropertySimpler, more declarative syntax
Events (Click, Changed)EventCallback<T>Async event handling
+
+

Step-by-Step Migration Process

+

Step 1: Create the .razor File

+

Create a new Razor component file with the same name as your ASCX user control. Place it in a Components or Controls directory (this is a convention; Blazor has no requirement).

+

Example: PageHeader.razor (replaces PageHeader.ascx + PageHeader.ascx.cs)

+
@* PageHeader.razor *@
+
+<div class="page-header">
+    <h1>@Title</h1>
+    <p>@Subtitle</p>
+</div>
+
+@code {
+    [Parameter]
+    public string Title { get; set; }
+
+    [Parameter]
+    public string Subtitle { get; set; }
+}
+
+

Step 2: Remove Web Forms Syntax

+

Remove the <%@ Control %> directive and runat="server" attributes. Blazor doesn't use these.

+

Before: +

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="PageHeader.ascx.cs" Inherits="..." %>
+<asp:TextBox ID="searchBox" runat="server" />
+

+

After: +

<input type="text" @bind="searchQuery" />
+

+

Step 3: Convert Properties to Parameters

+

Properties that are set declaratively in markup must be decorated with [Parameter].

+

Before (Web Forms PageHeader.ascx.cs): +

public partial class PageHeader : UserControl
+{
+    public string Title { get; set; }
+    public string Subtitle { get; set; }
+    public string BackgroundColor { get; set; } = "white";
+}
+

+

After (Blazor PageHeader.razor): +

@code {
+    [Parameter]
+    public string Title { get; set; }
+
+    [Parameter]
+    public string Subtitle { get; set; }
+
+    [Parameter]
+    public string BackgroundColor { get; set; } = "white";
+}
+

+

Step 4: Convert Events to EventCallback

+

Web Forms events (Click, TextChanged, etc.) become EventCallback<T> parameters in Blazor.

+

Before (Web Forms): +

public event EventHandler SearchClicked;
+
+protected void SearchButton_Click(object sender, EventArgs e)
+{
+    SearchClicked?.Invoke(this, EventArgs.Empty);
+}
+

+
<asp:Button ID="SearchButton" runat="server" Text="Search" OnClick="SearchButton_Click" />
+
+

After (Blazor): +

<button @onclick="OnSearchClick">Search</button>
+
+@code {
+    [Parameter]
+    public EventCallback OnSearchClicked { get; set; }
+
+    private async Task OnSearchClick()
+    {
+        await OnSearchClicked.InvokeAsync();
+    }
+}
+

+

Step 5: Migrate Page Lifecycle

+

Web Forms user controls use Page_Load, Page_PreRender, and other lifecycle events. Blazor components use different hooks:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web FormsBlazorWhen It Runs
Page_Load (if !IsPostBack)OnInitializedAsyncOnce, when component first loads
Page_Load (every postback)OnParametersSetAsyncWhen parameters change or component re-initializes
Page_PreRenderOnAfterRenderAsyncAfter render tree is built, before DOM update
Dispose / OnUnloadIAsyncDisposableWhen component is destroyed
+

Example: Initialization Logic

+

Before (Web Forms Page_Load): +

protected void Page_Load(object sender, EventArgs e)
+{
+    if (!IsPostBack)
+    {
+        LoadEmployeeData();
+    }
+}
+
+private void LoadEmployeeData()
+{
+    // Fetch from database
+}
+

+

After (Blazor OnInitializedAsync): +

@code {
+    protected override async Task OnInitializedAsync()
+    {
+        await LoadEmployeeData();
+    }
+
+    private async Task LoadEmployeeData()
+    {
+        // Fetch from database
+    }
+}
+

+

Step 6: Replace Data Binding Syntax

+

Web Forms uses <%# Eval("PropertyName") %> for data binding. Blazor uses direct property access with @.

+

Before (Web Forms Repeater inside ASCX): +

<asp:Repeater ID="EmployeeRepeater" runat="server">
+    <ItemTemplate>
+        <div>
+            <h3><%# Eval("FirstName") %> <%# Eval("LastName") %></h3>
+            <p><%# Eval("Department") %></p>
+        </div>
+    </ItemTemplate>
+</asp:Repeater>
+

+

After (Blazor Razor component with @foreach): +

@if (Employees != null)
+{
+    @foreach (var emp in Employees)
+    {
+        <div>
+            <h3>@emp.FirstName @emp.LastName</h3>
+            <p>@emp.Department</p>
+        </div>
+    }
+}
+
+@code {
+    [Parameter]
+    public IEnumerable<Employee> Employees { get; set; }
+}
+

+

Step 7: Replace FindControl with @ref or Cascading Parameters

+

Web Forms allowed FindControl("ID") to locate child controls. Blazor uses @ref or cascading parameters instead.

+

Before (Web Forms — cross-boundary FindControl): +

public partial class MyUserControl : UserControl
+{
+    protected void SomeMethod()
+    {
+        var textBox = (TextBox)FindControl("MyTextBox");
+        var value = textBox.Text;
+    }
+}
+

+

After (Blazor — use @ref): +

<input @ref="myTextBox" type="text" />
+
+@code {
+    private ElementReference myTextBox;
+
+    private async Task SomeMethod()
+    {
+        var value = await JS.InvokeAsync<string>("eval", "document.getElementById('" + myTextBox.Id + "').value");
+        // Or better: use two-way binding with @bind
+    }
+}
+

+

For child component references (not HTML elements), use @ref:

+
<ChildComponent @ref="childComponentRef" />
+
+@code {
+    private ChildComponent childComponentRef;
+
+    private void CallChildMethod()
+    {
+        childComponentRef.SomePublicMethod();
+    }
+}
+
+
+

Complete Example: EmployeeList Control Migration

+

Web Forms ASCX Control

+

EmployeeList.ascx: +

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="EmployeeList.ascx.cs" Inherits="DepartmentPortal.Controls.EmployeeList" %>
+
+<div class="employee-list">
+    <input type="text" id="searchBox" placeholder="Search..." onkeyup="<%# GetJavaScriptSearch() %>" />
+
+    <asp:Repeater ID="EmployeeRepeater" runat="server" OnItemCommand="EmployeeRepeater_ItemCommand">
+        <HeaderTemplate>
+            <table class="table">
+                <thead>
+                    <tr>
+                        <th>Name</th>
+                        <th>Department</th>
+                        <th>Actions</th>
+                    </tr>
+                </thead>
+                <tbody>
+        </HeaderTemplate>
+        <ItemTemplate>
+            <tr>
+                <td><%# Eval("FirstName") %> <%# Eval("LastName") %></td>
+                <td><%# Eval("Department") %></td>
+                <td>
+                    <asp:LinkButton ID="EditButton" runat="server" 
+                        CommandName="Edit" CommandArgument='<%# Eval("ID") %>'>Edit</asp:LinkButton>
+                </td>
+            </tr>
+        </ItemTemplate>
+        <FooterTemplate>
+                </tbody>
+            </table>
+        </FooterTemplate>
+    </asp:Repeater>
+</div>
+

+

EmployeeList.ascx.cs: +

public partial class EmployeeList : UserControl
+{
+    public IEnumerable<Employee> Employees { get; set; }
+
+    public event EventHandler<int> EditRequested;
+
+    protected void Page_Load(object sender, EventArgs e)
+    {
+        if (!IsPostBack && Employees != null)
+        {
+            BindData();
+        }
+    }
+
+    private void BindData()
+    {
+        EmployeeRepeater.DataSource = Employees;
+        EmployeeRepeater.DataBind();
+    }
+
+    protected void EmployeeRepeater_ItemCommand(object source, RepeaterCommandEventArgs e)
+    {
+        if (e.CommandName == "Edit")
+        {
+            EditRequested?.Invoke(this, int.Parse((string)e.CommandArgument));
+        }
+    }
+
+    private string GetJavaScriptSearch()
+    {
+        return "alert('Search not implemented');";
+    }
+}
+

+

Blazor Razor Component Equivalent

+

EmployeeList.razor: +

<div class="employee-list">
+    <input type="text" placeholder="Search..." @onkeyup="OnSearch" />
+
+    @if (FilteredEmployees?.Any() == true)
+    {
+        <table class="table">
+            <thead>
+                <tr>
+                    <th>Name</th>
+                    <th>Department</th>
+                    <th>Actions</th>
+                </tr>
+            </thead>
+            <tbody>
+                @foreach (var emp in FilteredEmployees)
+                {
+                    <tr>
+                        <td>@emp.FirstName @emp.LastName</td>
+                        <td>@emp.Department</td>
+                        <td>
+                            <button @onclick="() => OnEdit(emp.ID)">Edit</button>
+                        </td>
+                    </tr>
+                }
+            </tbody>
+        </table>
+    }
+    else
+    {
+        <p>No employees found.</p>
+    }
+</div>
+
+@code {
+    [Parameter]
+    public IEnumerable<Employee> Employees { get; set; }
+
+    [Parameter]
+    public EventCallback<int> OnEditRequested { get; set; }
+
+    private IEnumerable<Employee> FilteredEmployees { get; set; }
+    private string SearchTerm { get; set; } = "";
+
+    protected override async Task OnParametersSetAsync()
+    {
+        await ApplyFilter();
+    }
+
+    private async Task OnSearch(KeyboardEventArgs e)
+    {
+        SearchTerm = await JS.InvokeAsync<string>("getInputValue", e.Target);
+        await ApplyFilter();
+    }
+
+    private async Task ApplyFilter()
+    {
+        FilteredEmployees = string.IsNullOrEmpty(SearchTerm)
+            ? Employees
+            : Employees.Where(e => 
+                e.FirstName.Contains(SearchTerm, StringComparison.OrdinalIgnoreCase) ||
+                e.LastName.Contains(SearchTerm, StringComparison.OrdinalIgnoreCase));
+
+        // Optional: debounce or throttle the filter
+        await Task.Delay(100);
+    }
+
+    private async Task OnEdit(int employeeId)
+    {
+        await OnEditRequested.InvokeAsync(employeeId);
+    }
+}
+

+

Key Differences in the Migration

+
    +
  1. No repeater control — Use @foreach for list rendering
    2. +
  2. No Register directive — Import in _Imports.razor instead
    3. +
  3. No FindControl — Use event callbacks or @ref
    4. +
  4. Data binding is automatic — Employees property is directly accessible in the template
    5. +
  5. Events are async — Use EventCallback<T> and await
    6. +
  6. Lifecycle is different — OnParametersSetAsync replaces Page_Load with IsPostBack check
    7. +
+
+

Common Pitfalls and Solutions

+

1. Parameter Changes Not Triggering Re-Render

+

Problem: User control properties change, but the component doesn't update.

+

Solution: Use OnParametersSetAsync() to react to parameter changes, or use @bind for two-way binding.

+
@code {
+    [Parameter]
+    public string FilterCriteria { get; set; }
+
+    protected override async Task OnParametersSetAsync()
+    {
+        // This runs whenever FilterCriteria changes
+        await RefreshData();
+    }
+}
+
+

2. Accessing HTML Element Values

+

Problem: Trying to use FindControl on HTML elements instead of components.

+

Solution: Use @ref for ElementReference, or use @bind for two-way data binding.

+
<input @bind="searchQuery" type="text" />
+
+@code {
+    private string searchQuery = "";
+
+    // searchQuery is automatically updated as the user types
+}
+
+

3. Child Component Not Responding to Parent Updates

+

Problem: Parent passes new data, but child component doesn't reflect the change.

+

Solution: Ensure the child component has [Parameter] properties and responds in OnParametersSetAsync.

+
@* Parent *@
+<ChildList Items="filteredItems" />
+
+@* Child *@
+<div>
+    @foreach (var item in Items)
+    {
+        <p>@item.Name</p>
+    }
+</div>
+
+@code {
+    [Parameter]
+    public IEnumerable<Item> Items { get; set; }
+}
+
+

4. Lost Context in Nested Components

+

Problem: Deep component hierarchies lose access to ancestor state.

+

Solution: Use cascading parameters to pass data down through multiple levels.

+
@* Ancestor *@
+<CascadingValue Value="CurrentUser">
+    <ChildComponent />
+</CascadingValue>
+
+@* Descendant (multiple levels deep) *@
+@code {
+    [CascadingParameter]
+    public User CurrentUser { get; set; }
+}
+
+
+

State Management in User Controls

+

Using ViewStateDictionary for Component State

+

When migrating user controls that rely on ViewState, use ViewStateDictionary (available on BaseWebFormsComponent and WebFormsPageBase) to store component-level state that persists across postbacks.

+

Basic ViewState Usage

+

Before (Web Forms ASCX): +

public partial class SearchResultsControl : UserControl
+{
+    protected void Page_Load(object sender, EventArgs e)
+    {
+        if (!IsPostBack)
+        {
+            ViewState["CurrentPage"] = 1;
+            ViewState["SearchTerm"] = "";
+        }
+    }
+
+    protected void NextButton_Click(object sender, EventArgs e)
+    {
+        int page = (int)ViewState["CurrentPage"];
+        ViewState["CurrentPage"] = page + 1;
+        LoadResults();
+    }
+
+    private void LoadResults()
+    {
+        string term = (string)ViewState["SearchTerm"];
+        // Load and bind data...
+    }
+}
+

+

After (Blazor): +

@inherits BaseWebFormsComponent
+
+<div>
+    <input @bind="_searchTerm" placeholder="Search..." />
+    <Button Text="Search" @onclick="OnSearch" />
+    <Button Text="Next" @onclick="OnNext" />
+</div>
+
+@code {
+    private string _searchTerm = "";
+
+    protected override void OnInitialized()
+    {
+        if (!IsPostBack)
+        {
+            ViewState.Set("CurrentPage", 1);
+            ViewState.Set("SearchTerm", "");
+        }
+        else
+        {
+            // Restore state on postback
+            int page = ViewState.GetValueOrDefault<int>("CurrentPage", 1);
+            _searchTerm = ViewState.GetValueOrDefault<string>("SearchTerm", "");
+        }
+    }
+
+    private void OnSearch()
+    {
+        ViewState.Set("CurrentPage", 1);
+        ViewState.Set("SearchTerm", _searchTerm);
+    }
+
+    private void OnNext()
+    {
+        int page = ViewState.GetValueOrDefault<int>("CurrentPage", 1);
+        ViewState.Set("CurrentPage", page + 1);
+    }
+}
+

+

Type-Safe ViewState Access

+

For cleaner, more maintainable code, use the GetValueOrDefault<T>() and Set<T>() methods:

+
@code {
+    private int GetCurrentPage()
+    {
+        return ViewState.GetValueOrDefault<int>("CurrentPage", 1);
+    }
+
+    private void SetCurrentPage(int page)
+    {
+        ViewState.Set("CurrentPage", page);
+    }
+
+    private void OnNext()
+    {
+        int page = GetCurrentPage();
+        SetCurrentPage(page + 1);
+    }
+}
+
+

Sharing State Between Components

+

When multiple child components need to share state, store it in the parent component's ViewState and pass it down via parameters:

+
@* Parent Component *@
+<ChildFilter @ref="_filterControl" 
+             OnFilterApplied="@OnFilterChanged" />
+<ChildResults Items="@_results" />
+
+@code {
+    private ChildFilter _filterControl;
+    private List<Item> _results;
+
+    protected override void OnInitialized()
+    {
+        if (!IsPostBack)
+        {
+            _results = LoadDefaultResults();
+            ViewState.Set("LastFilter", "");
+        }
+    }
+
+    private void OnFilterChanged(string filter)
+    {
+        ViewState.Set("LastFilter", filter);
+        _results = ApplyFilter(_results, filter);
+    }
+}
+
+@* Child Filter Component *@
+<input @bind="_filterText" />
+<button @onclick="OnApplyFilter">Apply</button>
+
+@code {
+    [Parameter]
+    public EventCallback<string> OnFilterApplied { get; set; }
+
+    private string _filterText = "";
+
+    private async Task OnApplyFilter()
+    {
+        await OnFilterApplied.InvokeAsync(_filterText);
+    }
+}
+
+
+

Event Handling and Component Communication

+

Converting Web Forms Events to EventCallback

+

Web Forms user controls expose events that parent pages listen to. In Blazor, use EventCallback<T> parameters for bidirectional communication.

+

Simple Event Callback (No Payload)

+

Before (Web Forms): +

public partial class ConfirmDialog : UserControl
+{
+    public event EventHandler OnOK;
+    public event EventHandler OnCancel;
+
+    protected void OKButton_Click(object sender, EventArgs e)
+    {
+        OnOK?.Invoke(this, EventArgs.Empty);
+    }
+
+    protected void CancelButton_Click(object sender, EventArgs e)
+    {
+        OnCancel?.Invoke(this, EventArgs.Empty);
+    }
+}
+

+

After (Blazor): +

<div class="dialog">
+    <p>@Message</p>
+    <Button Text="OK" @onclick="OnOKClick" />
+    <Button Text="Cancel" @onclick="OnCancelClick" />
+</div>
+
+@code {
+    [Parameter]
+    public string Message { get; set; }
+
+    [Parameter]
+    public EventCallback OnOK { get; set; }
+
+    [Parameter]
+    public EventCallback OnCancel { get; set; }
+
+    private async Task OnOKClick()
+    {
+        await OnOK.InvokeAsync();
+    }
+
+    private async Task OnCancelClick()
+    {
+        await OnCancel.InvokeAsync();
+    }
+}
+

+

Event Callback With Data (Typed Payload)

+

Before (Web Forms): +

public partial class ItemSelector : UserControl
+{
+    public event EventHandler<int> OnItemSelected;
+
+    protected void ItemRepeater_ItemCommand(object source, RepeaterCommandEventArgs e)
+    {
+        if (e.CommandName == "Select")
+        {
+            int itemId = int.Parse((string)e.CommandArgument);
+            OnItemSelected?.Invoke(this, itemId);
+        }
+    }
+}
+

+

After (Blazor): +

<ul>
+    @foreach (var item in Items)
+    {
+        <li>
+            @item.Name
+            <button @onclick="() => OnSelectItem(item.ID)">Select</button>
+        </li>
+    }
+</ul>
+
+@code {
+    [Parameter]
+    public List<Item> Items { get; set; }
+
+    [Parameter]
+    public EventCallback<int> OnItemSelected { get; set; }
+
+    private async Task OnSelectItem(int itemId)
+    {
+        await OnItemSelected.InvokeAsync(itemId);
+    }
+
+    public class Item
+    {
+        public int ID { get; set; }
+        public string Name { get; set; }
+    }
+}
+

+

Parent Component Using Event Callbacks

+
@page "/demo"
+
+<ConfirmDialog Message="Are you sure?" 
+               OnOK="@OnConfirmed" 
+               OnCancel="@OnCancelled" />
+
+<ItemSelector Items="@_items" 
+              OnItemSelected="@OnItemSelected" />
+
+@code {
+    private List<Item> _items = new();
+
+    private void OnConfirmed()
+    {
+        Console.WriteLine("User confirmed");
+    }
+
+    private void OnCancelled()
+    {
+        Console.WriteLine("User cancelled");
+    }
+
+    private void OnItemSelected(int itemId)
+    {
+        Console.WriteLine($"Selected item: {itemId}");
+    }
+}
+
+
+

PostBack Patterns: IsPostBack and ViewState Integration

+

Understanding IsPostBack in Components

+

IsPostBack indicates whether the current render is a first-time initialization or a subsequent postback/re-render. Combined with ViewState, this enables Web Forms-style initialization patterns.

+

IsPostBack Detection Behavior

+
    +
  • SSR (Server-Side Rendering) — Returns true when the HTTP request method is POST (form submission)
    • +
  • ServerInteractive (Blazor WebSocket) — Returns true after the component has initialized once
    • +
+

One-Time Initialization with IsPostBack

+
@inherits BaseWebFormsComponent
+
+<div>
+    <p>Items loaded: @_items.Count</p>
+    <button @onclick="OnRefresh">Refresh Data</button>
+</div>
+
+@code {
+    private List<string> _items = new();
+
+    protected override async Task OnInitializedAsync()
+    {
+        if (!IsPostBack)
+        {
+            // First render: load data from database
+            _items = await FetchItemsFromDatabase();
+        }
+        // On postback: _items retains its previous value
+    }
+
+    private async Task OnRefresh()
+    {
+        _items = await FetchItemsFromDatabase();
+    }
+
+    private async Task<List<string>> FetchItemsFromDatabase()
+    {
+        // Simulate database call
+        await Task.Delay(100);
+        return new() { "Item1", "Item2", "Item3" };
+    }
+}
+
+

Combining IsPostBack with ViewState

+

For SSR scenarios where state must survive form POSTs, use both IsPostBack and ViewState:

+
@page "/cart"
+@inherits WebFormsPageBase
+
+<form method="post">
+    <div>
+        <h2>Shopping Cart</h2>
+        <input @bind="_itemName" placeholder="Item name" />
+        <Button Text="Add Item" @onclick="OnAddItem" />
+    </div>
+
+    @if (_cartItems?.Any() == true)
+    {
+        <ul>
+            @foreach (var item in _cartItems)
+            {
+                <li>@item</li>
+            }
+        </ul>
+    }
+
+    <RenderViewStateField />
+</form>
+
+@code {
+    private string _itemName = "";
+    private List<string> _cartItems = new();
+
+    protected override void OnInitialized()
+    {
+        if (!IsPostBack)
+        {
+            // First render: initialize cart from database
+            _cartItems = new();
+            ViewState.Set("CartItems", _cartItems);
+        }
+        else
+        {
+            // Postback: restore cart from ViewState
+            _cartItems = ViewState.GetValueOrDefault<List<string>>("CartItems", new());
+        }
+    }
+
+    private void OnAddItem()
+    {
+        if (!string.IsNullOrEmpty(_itemName))
+        {
+            _cartItems.Add(_itemName);
+            ViewState.Set("CartItems", _cartItems);
+            _itemName = "";
+        }
+    }
+}
+
+
+

Gradual Migration: Coexisting ASCX and Razor Components

+

When migrating a large application, you don't need to convert all user controls at once. ASCX controls and Razor components can coexist during the transition period.

+

Migration Timeline Strategy

+
    +
  1. Phase 1: Simple Controls — Migrate stateless presentational controls first
    2. +
  2. Phase 2: Event-Driven Controls — Migrate controls with events and callbacks
    3. +
  3. Phase 3: Stateful Controls — Migrate complex controls with ViewState
    4. +
  4. Phase 4: Integration — Update parent pages to use new Razor versions
    5. +
+

Parallel Implementation Pattern

+
@* Interim state: Both old ASCX and new Razor exist *@
+
+@* Page that uses OLD ASCX control *@
+<%@ Register TagPrefix="uc" TagName="OldSearch" Src="~/Controls/OldSearchBox.ascx" %>
+<uc:OldSearch ID="SearchControl" runat="server" />
+
+@* Same page (during transition) using NEW Razor component *@
+@* Import in _Imports.razor instead of Register directive *@
+<NewSearchBox @ref="_newSearchControl" 
+              OnSearch="@OnSearch" />
+
+

Wrapper Pattern for Gradual Rollout

+

Create a wrapper component that conditionally uses old or new implementations:

+
@* SearchBoxAdapter.razor - wraps old and new implementations *@
+@implements IAsyncDisposable
+
+@if (UseNewImplementation)
+{
+    <NewSearchBox OnSearch="@OnSearch" />
+}
+else
+{
+    <div @ref="_oldControlContainer"></div>
+}
+
+@code {
+    [Parameter]
+    public EventCallback<string> OnSearch { get; set; }
+
+    [Parameter]
+    public bool UseNewImplementation { get; set; } = false;
+
+    private ElementReference _oldControlContainer;
+
+    private async Task OnSearch(string term)
+    {
+        await OnSearch.InvokeAsync(term);
+    }
+
+    async ValueTask IAsyncDisposable.DisposeAsync()
+    {
+        // Cleanup old control if needed
+    }
+}
+
+

Use a configuration flag to control which implementation is active:

+
// Startup.cs or Program.cs
+builder.Services.AddSingleton<MigrationConfig>(new MigrationConfig
+{
+    UseNewSearchBox = Environment.GetEnvironmentVariable("ENABLE_NEW_SEARCHBOX") == "true"
+});
+
+
+

Complete Working Examples

+

Example 1: Product Catalog Control with ViewState and EventCallback

+

This example shows a realistic user control migration that includes state management, filtering, and events.

+

Web Forms ASCX (Before)

+

ProductCatalog.ascx: +

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="ProductCatalog.ascx.cs" Inherits="eCommerce.Controls.ProductCatalog" %>
+
+<div class="product-catalog">
+    <div class="filters">
+        <asp:DropDownList ID="CategoryDropdown" runat="server" 
+            AutoPostBack="true" OnSelectedIndexChanged="CategoryDropdown_SelectedIndexChanged">
+            <asp:ListItem Value="">All Categories</asp:ListItem>
+            <asp:ListItem Value="Electronics">Electronics</asp:ListItem>
+            <asp:ListItem Value="Clothing">Clothing</asp:ListItem>
+        </asp:DropDownList>
+    </div>
+
+    <asp:Repeater ID="ProductRepeater" runat="server">
+        <ItemTemplate>
+            <div class="product-card">
+                <h3><%# Eval("Name") %></h3>
+                <p>Price: $<%# Eval("Price", "{0:0.00}") %></p>
+                <asp:LinkButton ID="AddCartButton" runat="server" 
+                    CommandName="AddCart" CommandArgument='<%# Eval("ID") %>'>
+                    Add to Cart
+                </asp:LinkButton>
+            </div>
+        </ItemTemplate>
+    </asp:Repeater>
+</div>
+

+

ProductCatalog.ascx.cs: +

public partial class ProductCatalog : UserControl
+{
+    public event EventHandler<int> OnProductAdded;
+
+    protected void Page_Load(object sender, EventArgs e)
+    {
+        if (!IsPostBack)
+        {
+            ViewState["CurrentCategory"] = "";
+            LoadProducts("");
+        }
+    }
+
+    protected void CategoryDropdown_SelectedIndexChanged(object sender, EventArgs e)
+    {
+        string category = CategoryDropdown.SelectedValue;
+        ViewState["CurrentCategory"] = category;
+        LoadProducts(category);
+    }
+
+    protected void ProductRepeater_ItemCommand(object source, RepeaterCommandEventArgs e)
+    {
+        if (e.CommandName == "AddCart")
+        {
+            int productId = int.Parse((string)e.CommandArgument);
+            OnProductAdded?.Invoke(this, productId);
+        }
+    }
+
+    private void LoadProducts(string category)
+    {
+        var products = GetProductsByCategory(category);
+        ProductRepeater.DataSource = products;
+        ProductRepeater.DataBind();
+    }
+
+    private List<Product> GetProductsByCategory(string category)
+    {
+        // Simulate database query
+        return new()
+        {
+            new Product { ID = 1, Name = "Laptop", Category = "Electronics", Price = 999.99m },
+            new Product { ID = 2, Name = "Shirt", Category = "Clothing", Price = 29.99m }
+        };
+    }
+}
+
+public class Product
+{
+    public int ID { get; set; }
+    public string Name { get; set; }
+    public string Category { get; set; }
+    public decimal Price { get; set; }
+}
+

+

Blazor Razor Component (After)

+

ProductCatalog.razor: +

<div class="product-catalog">
+    <div class="filters">
+        <select @onchange="OnCategoryChanged">
+            <option value="">All Categories</option>
+            <option value="Electronics">Electronics</option>
+            <option value="Clothing">Clothing</option>
+        </select>
+    </div>
+
+    @if (_filteredProducts?.Any() == true)
+    {
+        <div class="product-grid">
+            @foreach (var product in _filteredProducts)
+            {
+                <div class="product-card">
+                    <h3>@product.Name</h3>
+                    <p>Price: $@product.Price.ToString("0.00")</p>
+                    <Button Text="Add to Cart" @onclick="() => OnAddToCart(product.ID)" />
+                </div>
+            }
+        </div>
+    }
+    else
+    {
+        <p>No products found.</p>
+    }
+</div>
+
+@code {
+    [Parameter]
+    public EventCallback<int> OnProductAdded { get; set; }
+
+    private List<Product> _allProducts = new();
+    private List<Product> _filteredProducts = new();
+    private string _currentCategory = "";
+
+    protected override void OnInitialized()
+    {
+        if (!IsPostBack)
+        {
+            // First render: load all products
+            _allProducts = GetAllProducts();
+            _filteredProducts = _allProducts;
+            ViewState.Set("CurrentCategory", "");
+        }
+        else
+        {
+            // Postback: restore filter state
+            _currentCategory = ViewState.GetValueOrDefault<string>("CurrentCategory", "");
+            _allProducts = GetAllProducts();
+            ApplyFilter(_currentCategory);
+        }
+    }
+
+    private async Task OnCategoryChanged(ChangeEventArgs e)
+    {
+        _currentCategory = e.Value?.ToString() ?? "";
+        ViewState.Set("CurrentCategory", _currentCategory);
+        ApplyFilter(_currentCategory);
+        await Task.CompletedTask;
+    }
+
+    private void ApplyFilter(string category)
+    {
+        _filteredProducts = string.IsNullOrEmpty(category)
+            ? _allProducts
+            : _allProducts.Where(p => p.Category == category).ToList();
+    }
+
+    private async Task OnAddToCart(int productId)
+    {
+        await OnProductAdded.InvokeAsync(productId);
+    }
+
+    private List<Product> GetAllProducts()
+    {
+        return new()
+        {
+            new Product { ID = 1, Name = "Laptop", Category = "Electronics", Price = 999.99m },
+            new Product { ID = 2, Name = "Shirt", Category = "Clothing", Price = 29.99m },
+            new Product { ID = 3, Name = "Tablet", Category = "Electronics", Price = 499.99m }
+        };
+    }
+
+    public class Product
+    {
+        public int ID { get; set; }
+        public string Name { get; set; }
+        public string Category { get; set; }
+        public decimal Price { get; set; }
+    }
+}
+

+

Usage in a Parent Page

+

Web Forms (Before): +

<%@ Page Language="C#" %>
+<%@ Register TagPrefix="uc" TagName="ProductCatalog" Src="~/Controls/ProductCatalog.ascx" %>
+
+<form runat="server">
+    <h1>Shopping</h1>
+    <uc:ProductCatalog ID="catalog" runat="server" OnProductAdded="Catalog_ProductAdded" />
+    <asp:Label ID="StatusLabel" runat="server" />
+
+    <script runat="server">
+        protected void Catalog_ProductAdded(object sender, int productId)
+        {
+            StatusLabel.Text = $"Added product {productId} to cart";
+        }
+    </script>
+</form>
+

+

Blazor (After): +

@page "/shopping"
+
+<h1>Shopping</h1>
+<ProductCatalog OnProductAdded="@OnCatalogProductAdded" />
+@if (!string.IsNullOrEmpty(_statusMessage))
+{
+    <p>@_statusMessage</p>
+}
+
+@code {
+    private string _statusMessage = "";
+
+    private void OnCatalogProductAdded(int productId)
+    {
+        _statusMessage = $"Added product {productId} to cart";
+    }
+}
+

+

Example 2: Multi-Step Form Control with IsPostBack

+

This example demonstrates a form control that maintains state across steps using ViewState and IsPostBack.

+

Web Forms ASCX (Before)

+

RegistrationWizard.ascx.cs: +

public partial class RegistrationWizard : UserControl
+{
+    protected void Page_Load(object sender, EventArgs e)
+    {
+        if (!IsPostBack)
+        {
+            ViewState["CurrentStep"] = 1;
+            ShowStep(1);
+        }
+        else
+        {
+            int step = (int)ViewState["CurrentStep"];
+            ShowStep(step);
+        }
+    }
+
+    protected void NextButton_Click(object sender, EventArgs e)
+    {
+        int currentStep = (int)ViewState["CurrentStep"];
+
+        if (ValidateStep(currentStep))
+        {
+            SaveStepData(currentStep);
+            int nextStep = currentStep + 1;
+
+            if (nextStep <= 3)
+            {
+                ViewState["CurrentStep"] = nextStep;
+                ShowStep(nextStep);
+            }
+            else
+            {
+                SubmitRegistration();
+            }
+        }
+    }
+
+    private void SaveStepData(int step)
+    {
+        if (step == 1)
+        {
+            ViewState["FirstName"] = FirstNameTextBox.Text;
+            ViewState["LastName"] = LastNameTextBox.Text;
+        }
+        // ... additional steps
+    }
+
+    private void ShowStep(int step)
+    {
+        Step1Panel.Visible = (step == 1);
+        Step2Panel.Visible = (step == 2);
+        Step3Panel.Visible = (step == 3);
+    }
+}
+

+

Blazor Razor Component (After)

+

RegistrationWizard.razor: +

@inherits BaseWebFormsComponent
+
+<div class="wizard">
+    @if (CurrentStep == 1)
+    {
+        <div class="step">
+            <h3>Step 1: Personal Information</h3>
+            <input @bind="_firstName" placeholder="First Name" />
+            <input @bind="_lastName" placeholder="Last Name" />
+        </div>
+    }
+    else if (CurrentStep == 2)
+    {
+        <div class="step">
+            <h3>Step 2: Contact Information</h3>
+            <input @bind="_email" placeholder="Email" />
+            <input @bind="_phone" placeholder="Phone" />
+        </div>
+    }
+    else if (CurrentStep == 3)
+    {
+        <div class="step">
+            <h3>Step 3: Confirmation</h3>
+            <p>Name: @(ViewState.GetValueOrDefault<string>("FirstName", "")) @(ViewState.GetValueOrDefault<string>("LastName", ""))</p>
+            <p>Email: @(ViewState.GetValueOrDefault<string>("Email", ""))</p>
+        </div>
+    }
+
+    <div class="buttons">
+        @if (CurrentStep > 1)
+        {
+            <Button Text="Back" @onclick="OnBack" />
+        }
+        @if (CurrentStep < 3)
+        {
+            <Button Text="Next" @onclick="OnNext" />
+        }
+        else
+        {
+            <Button Text="Submit" @onclick="OnSubmit" />
+        }
+    </div>
+</div>
+
+@code {
+    [Parameter]
+    public EventCallback<RegistrationData> OnRegistrationComplete { get; set; }
+
+    private string _firstName = "";
+    private string _lastName = "";
+    private string _email = "";
+    private string _phone = "";
+
+    private int CurrentStep
+    {
+        get => ViewState.GetValueOrDefault<int>("CurrentStep", 1);
+        set => ViewState.Set("CurrentStep", value);
+    }
+
+    protected override void OnInitialized()
+    {
+        if (!IsPostBack)
+        {
+            CurrentStep = 1;
+            ViewState.Set("FirstName", "");
+            ViewState.Set("LastName", "");
+            ViewState.Set("Email", "");
+            ViewState.Set("Phone", "");
+        }
+        else
+        {
+            // Restore form fields from ViewState
+            _firstName = ViewState.GetValueOrDefault<string>("FirstName", "");
+            _lastName = ViewState.GetValueOrDefault<string>("LastName", "");
+            _email = ViewState.GetValueOrDefault<string>("Email", "");
+            _phone = ViewState.GetValueOrDefault<string>("Phone", "");
+        }
+    }
+
+    private async Task OnNext()
+    {
+        if (ValidateCurrentStep())
+        {
+            SaveCurrentStepData();
+            CurrentStep++;
+        }
+    }
+
+    private void OnBack()
+    {
+        SaveCurrentStepData();
+        CurrentStep--;
+    }
+
+    private async Task OnSubmit()
+    {
+        SaveCurrentStepData();
+
+        var data = new RegistrationData
+        {
+            FirstName = ViewState.GetValueOrDefault<string>("FirstName", ""),
+            LastName = ViewState.GetValueOrDefault<string>("LastName", ""),
+            Email = ViewState.GetValueOrDefault<string>("Email", ""),
+            Phone = ViewState.GetValueOrDefault<string>("Phone", "")
+        };
+
+        await OnRegistrationComplete.InvokeAsync(data);
+    }
+
+    private void SaveCurrentStepData()
+    {
+        switch (CurrentStep)
+        {
+            case 1:
+                ViewState.Set("FirstName", _firstName);
+                ViewState.Set("LastName", _lastName);
+                break;
+            case 2:
+                ViewState.Set("Email", _email);
+                ViewState.Set("Phone", _phone);
+                break;
+        }
+    }
+
+    private bool ValidateCurrentStep()
+    {
+        return CurrentStep switch
+        {
+            1 => !string.IsNullOrEmpty(_firstName) && !string.IsNullOrEmpty(_lastName),
+            2 => !string.IsNullOrEmpty(_email) && !string.IsNullOrEmpty(_phone),
+            _ => true
+        };
+    }
+
+    public class RegistrationData
+    {
+        public string FirstName { get; set; }
+        public string LastName { get; set; }
+        public string Email { get; set; }
+        public string Phone { get; set; }
+    }
+}
+

+
+

Using BWFC Components to Ease Migration

+

If your user controls use BWFC compatibility components (e.g., WebControl, Repeater, Button), the migration is even smoother:

+
@* ASCX using BWFC Button *@
+<uc:SearchBox>
+    <BlazorWebFormsComponents:Button ID="SearchButton" runat="server" Text="Search" OnClick="..." />
+</uc:SearchBox>
+
+@* Blazor equivalent *@
+<SearchBox>
+    <Button Text="Search" @onclick="OnSearch" />
+</SearchBox>
+
+

BWFC components handle attribute rendering and styling automatically, so the markup conversion is nearly 1:1.

+
+

See Also

+ +
+

References

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/migration_readiness/index.html b/site/Migration/migration_readiness/index.html new file mode 100644 index 000000000..a31bd4f0f --- /dev/null +++ b/site/Migration/migration_readiness/index.html @@ -0,0 +1,4627 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Web Forms Application Migration Readiness - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Web Forms Application Migration Readiness

+ +

This document is intended as a primer for prospective teams to review in preparation for migrating their Web Forms applications to Server-Side Blazor. We believe the migration is a multi-step process and this application review and preparation is the first step in migrating / rewriting an application using Blazor.

+

Definitions

+

Throughout this document, we will refer to several framework and technology terms. This section will clarify those terms.

+
    +
  • Web Forms
    • +
  • The ASP.NET user-interface technology that started with the release in 2002 and is typically identified by applications with web pages that have a .ASPX file-extension
    • +
  • MVC
    • +
  • Model-View-Controller architecture introduced in 2009 as an alternative user-interface framework for ASP.NET developers. A project structure that uses the MVC framework typically has 3 or 4 folders in it named Areas, Models, Views, Controllers
    • +
  • Razor Views
    • +
  • The template technology uses by modern ASP.NET MVC and ASP.NET Core applications. Typically, these files are found in the Views folder and have a .cshtml file-extension
    • +
+

High-Level Requirements

+
    +
  • ASPX in-line Visual Basic not supported on Razor components in .NET Core
    • +
  • Convert to C# or move out to a class library
    • +
  • No data source controls on ASPX pages
    • +
  • Business logic needs to be convertible to .NET Core
    • +
  • 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
    • +
  • These event-handlers do not exist and function the same way in Blazor. Avoid acting outside of the Load event. The actions you are taking in Load can be executed at the conclusion of the Initialize event in Blazor
    • +
  • Use a repository pattern with interfaces declared for the repositories
    • +
  • Inject the concrete implementation of the data access technology. It MAY change to HTTP access at some point in the future
    • +
  • Minimal code embedded in ASPX files - this code will need to be updated to work with the components, where they were using full-featured controls.
    • +
  • No calls through the control hierarchy. E.g. FindControl()
    • +
  • Any hybrid applications that contains both MVC and Web Forms user interface content will take some extra work to be converted, as the MVC components will need to be converted to ASP.NET Core
    • +
  • System.Confuguration.ConfigurationManager access will need to be rewritten to use Microsoft.Extensions.Configuration.IConfiguration objects that are injected
    • +
  • Push configuration access to a repository class object that can be migrated to the new Configuration model in .NET Core
    • +
  • HttpContext.Current access will need to be reevaluated. Direct HttpContext access should be avoided in Blazor
    • +
  • Custom components will need to be rewritten
    • +
  • User controls .ASCX files should be converted to Blazor components
    • +
  • HttpHandlers and HttpModules will need to be rewritten as ASP.NET Core middleware
    • +
  • MasterPages can be converted to Layout components
    • +
  • Mobile device detection is not available as part of Blazor. Site.mobile.master will not be directly used by the framework.
    • +
  • Instead of using an alternate rendering strategy for mobile, we recommend you embrace an adaptive rendering strategy to ensure that mobile device visitors to your application get a good experience
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/Migration/readme/index.html b/site/Migration/readme/index.html new file mode 100644 index 000000000..a3465225d --- /dev/null +++ b/site/Migration/readme/index.html @@ -0,0 +1,4960 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Getting started - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Getting started

+ +

Migration might not be the correct term for this process, it could appear to be more of a rewrite using Blazor. In this article, you will learn how to get started rewriting your Web Forms application using Blazor with the Blazor Web Forms Components package.

+

The output project from this operation will be a .NET Core 3.1 project running server-side Blazor. This is the current desired result as this is the supported LTS version of .NET Core and Blazor that was published in December 2019. With the schedule of .NET releases (as of Feb. 2020), we should expect to update to the next LTS version, .NET 6 between November 2021 and November 2022.

+

Step 0 - Acknowledgement

+

The first step is a step of acknowledgement. This process is not 100% and is not guaranteed to deliver a Blazor application without some amount of rewriting. Applications are written in many different ways, and the tools provided here are attempting to get your project CLOSE to Blazor so that you have to rewrite as little code as possible.

+

Step 1 - Readiness

+

There are good application architectures and there are not-so-good application architectures to be considered for migration to Blazor. We've written another document to help you evaluate the readiness of your application for migration. It is recommended you read through that documentation to understand what makes an application better prepared for migration to Blazor.

+

Step 2 - Migrate Business Logic to .NET Standard

+

.NET Standard is the new recommended way to package and reuse business logic across projects and .NET runtimes. We recommend you migrate: + - Any class libraries referenced + - Any classes in your web project that do NOT directly communicate with the web request or response

+

There is a separate strategy document with instructions to migrate your code to .NET Standard libraries. The goal of the exercise is to place all of your business logic into .NET Standard 2.0 libraries. This version of .NET Standard will allow you to reference the libraries in both your existing Web Forms application and in your new Blazor application.

+

A side benefit: this is a good architecture practice that should allow you to test your business logic independently from your web project. Try starting a unit test project with xUnit, NUnit or MSTest to exercise some of your business logic. You will be able to run your tests either in the Visual Studio Test Runner or at the command line using dotnet test

+

Step 3 - Create a new Blazor Server Project

+

Create your new Blazor Server-Side project either in Visual Studio 2019, Visual Studio for Mac, or at the command line. With Visual Studio, follow these steps:

+
+
+

ADD IMAGES

+
+
+

At the command-line you can execute the following command to create your Blazor Server-Side project:

+

dotnet new blazorserver -f netcoreapp3.1 -o <<DESTINATION FOLDER>>

+

Add a NuGet reference to the BlazorWebFormsComponents package on the command-line as follows:

+

dotnet add package Fritz.BlazorWebFormsComponents

+

Next, add references to the projects converted to .NET Standard in the previous step. In Visual Studio, follow these steps:

+
+
+

ADD IMAGES

+
+
+

On the command-line you can add references using the dotnet CLI tools in your Blazor Server-Side project folder with syntax like:

+

dotnet add reference ../MyLibrary

+

For more details, see the official .NET documentation for adding references.

+

Next, add a using statement in the existing ./_Imports.razor file for the BlazorWebFormsComponents:

+

@using BlazorWebFormsComponents

+

This will allow you to reference the components from the library directly. Without this statement you would have to create tags that look like <BlazorWebFormsComponents.ListView and that's just ugly. We want the simpler <ListView syntax that matches the markup used in ASP.NET

+

Step 4 - Master Pages

+

Master Pages in Web Forms are a combination of two concepts in Blazor: a host page and a Blazor layout. In Blazor Server-Side the host page is a razor page by default in Pages/_Host.cshtml that bootstraps the Blazor application and hosts all static CSS and JavaScript references.

+

You will want to place any CSS or JavaScript references from your MasterPages into this host page. The rest of your MasterPage layout inside the BODY tag will need to be migrated to a layout razor file. In the simplest scenario where you have one MasterPage with ONLY HTML content and it has one main content area, you will want to overwrite the content in Shared/MainLayout.razor

+

The default layout for your application will be defined in the App.razor file in a RouteView element as follows:

+
<Router AppAssembly="@typeof(Program).Assembly">
+    <Found Context="routeData">
+        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
+    </Found>
+    <NotFound>
+        <LayoutView Layout="@typeof(MainLayout)">
+            <p>Sorry, there's nothing at this address.</p>
+        </LayoutView>
+    </NotFound>
+</Router>
+
+

You can add additional rules in this file to route and choose different layouts as appropriate for your application.

+

For more complex scenarios and a walk-through with samples, read the MasterPages strategy documentation.

+

Back to top

+

Step 5 - User Controls

+

User Controls in Web Forms are identified by their .ascx extension and inclusion in other controls or pages. These controls most closely resemble Blazor components:

+
    +
  • Mixture of HTML and code
    • +
  • Inline functions in file with markup
    • +
  • Potential 'code-behind' partial class with more coded logic
    • +
+

Components have no direct reference to the structure and contents of the parent Page or MasterPage. If your controls rely on this capability of Web Forms, you will want to instead pass around a CascadingValue that your controls can receive as a CascadingParameter.

+

Components also do not have ViewState. We are considering implementing a ViewState-like object to help with conversion. If you were storing the state of things in ControlState or ViewState we recommend allocating a class-level field or parameter to store those values.

+

We recommend copying your HTML and code into a YOURCOMPONENT.razor file with the same name and place it in the same folder structure under a Components folder as was located in your web forms project. You can omit the <% control directive at the top of the file. You should then migrate any methods to a YOURCOMPONENT.razor.cs partial class.

+

References to <asp: components can be easily edited to use the matching components with these steps:

+

More information and advanced techniques can be found in the User Controls strategy document

+

Step 5.5 - JavaScript Setup (Optional)

+

BlazorWebFormsComponents requires a small JavaScript file to support features like OnClientClick. The easiest way to include it is to register the service in your Program.cs:

+
builder.Services.AddBlazorWebFormsComponents();
+
+

This automatically loads the JavaScript module when components render - no manual script tags needed!

+

Alternatively, you can add the script manually to your layout:

+
<script src="_content/Fritz.BlazorWebFormsComponents/js/Basepage.js"></script>
+
+

For more options and details, see the JavaScript Setup documentation.

+

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:

+
<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):

+
<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.

+

Common Properties on All Styled Controls

+

All BlazorWebFormsComponents controls that inherit from BaseStyledComponent support a set of common properties that match ASP.NET Web Forms' WebControl base class. This means properties like CssClass, BackColor, ForeColor, Font, Width, Height, BorderColor, BorderStyle, BorderWidth, Enabled, Visible, and ToolTip are available on every styled control — just as they are in Web Forms.

+
+

ToolTip renders as the HTML title attribute

+

The ToolTip property renders as the standard HTML title attribute, matching Web Forms behavior. This means browser-native tooltip display works automatically.

+
+
<Button Text="Save" ToolTip="Click to save your changes" />
+<TextBox @bind-Text="name" ToolTip="Enter your full name" />
+<Label Text="Status" ToolTip="Current processing status" />
+
+

You do not need to add ToolTip support per-control — it is inherited from the shared base and works on all styled controls including Button, TextBox, Label, Panel, CheckBox, DropDownList, GridView, and more.

+

Step 6 - Pages

+

Page migration is a process very similar to UserControls, except working on files with the .aspx extension.

+

The page starts with a directive to connect the markup to .NET code like the following:

+
<%@ Page Title="Home Page" Language="C#" MasterPageFile="~/Site.Master" AutoEventWireup="true" CodeBehind="Default.aspx.cs" Inherits="BeforeWebForms._Default" %>
+
+

These features defined here will be migrated / removed as follows: + - Title is not used in Blazor. We're looking into a work-around + - Language is not used - everything on the razor template is C# + - MasterPageFile is now a Layout and defined by default in the App.razor file. You can override it by adding a @layout MyLayout directive at the top of the file + - AutoEventWireup is not used in Blazor + - CodeBehind is not used in Blazor + - Inherits is converted to an @inherits directive that specifies the base class that the Blazor component should inherit from, typically ComponentBase.

+

Additionally, pages are defined with a route in Blazor. You will need to add a page directive to the top of the .razor file with syntax to declare what URL segment this page is listening on:

+
@page "/Home"
+
+

See the official Blazor documentation for more information on the Page directive and how to handle routing.

+

Step 7 - Custom Controls

+

At this time, these controls will need to be re-written to target the ComponentBase class instead. We have an issue opened to look into making migration of these classes easier, but it is targeted for later in the project.

+

More information and strategy for re-writing these controls can be found in the custom controls strategy document.

+

Step X - Convert inline Visual Basic

+

Use the tool from Telerik at: https://converter.telerik.com/

+

Follow-up: Clean Up with Roslyn Analyzers

+

After migrating your markup and code-behind, install the BlazorWebFormsComponents.Analyzers NuGet package to catch leftover Web Forms patterns in your C# code:

+
dotnet add package BlazorWebFormsComponents.Analyzers
+
+

The analyzer suite includes 8 rules that detect ViewState usage, IsPostBack checks, Response.Redirect() calls, Session access, missing [Parameter] attributes, and more. Each diagnostic comes with an automatic code fix. See the Roslyn Analyzers guide for full details.

+

Follow-up: Move components to Razor Component Library

+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/MigrationGuides/KnownFidelityDivergences/index.html b/site/MigrationGuides/KnownFidelityDivergences/index.html new file mode 100644 index 000000000..679e64769 --- /dev/null +++ b/site/MigrationGuides/KnownFidelityDivergences/index.html @@ -0,0 +1,5441 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Known Fidelity Divergences - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Known HTML Fidelity Divergences

+

Overview

+

BlazorWebFormsComponents (BWFC) aims to produce identical HTML output to the original ASP.NET Web Forms controls. This is a core design goal — matching the rendered DOM structure means existing CSS styles, JavaScript selectors, and visual layouts continue to work after migration.

+

In practice, however, some structural differences exist between BWFC output and the original Web Forms output. This page catalogs those known divergences so that developers can plan for them during migration.

+
+

Living Document

+

This page is updated as components are audited and refined. If you discover a divergence not listed here, please open an issue on GitHub.

+
+

ListView

+

Severity: 🔴 High — May break CSS/JS targeting

+

The BWFC ListView renders a fundamentally different DOM structure than the original Web Forms ListView control. This is the most significant fidelity divergence in the library.

+

What's Different

+ + + + + + + + + + + + + + + + + + + + + + + + + +
AspectWeb FormsBWFC
Group/Item wrapping<table> with <tr>/<td> wrapping for GroupTemplate, ItemTemplate, and LayoutTemplateTemplates rendered more directly with <div> wrappers
Structural depthDeeper nesting due to table-based layout scaffoldingFlatter structure with fewer wrapper elements
Output diff—~158-line structural diff in rendered output
+

In Web Forms, the ListView generates a table-based layout scaffold around templates, using <tr> and <td> elements to position group and item content. BWFC renders the user-provided templates more directly, producing a cleaner but structurally different DOM.

+

Impact

+
    +
  • CSS selectors targeting table > tr > td inside a ListView will not match
    • +
  • JavaScript that traverses the DOM hierarchy (e.g., parentNode.parentNode) may break
    • +
  • Layout behavior may differ if CSS relies on table display semantics
    • +
+

Workaround

+
    +
  • Use CSS that targets content classes and attributes rather than structural element selectors
    • +
  • Add data- attributes in your templates for reliable JS targeting
    • +
  • Prefer class-based selectors (.my-item) over structural selectors (table tr td)
    • +
+
/* Avoid — fragile structural selector */
+#myListView table tr td .item { ... }
+
+/* Prefer — class-based selector */
+#myListView .item { ... }
+
+

Calendar Sub-element IDs

+

Severity: 🟡 Medium — Partial impact

+

The BWFC Calendar component renders an id attribute on the outer <table> element, but it does not generate the hierarchical sub-element IDs that Web Forms produces.

+

What's Different

+

In Web Forms, the Calendar control generates IDs for individual structural elements using a hierarchical naming pattern:

+
<!-- Web Forms output -->
+<table id="Calendar1">
+  <tr>
+    <td id="Calendar1_Day1_1">1</td>
+    <td id="Calendar1_Day1_2">2</td>
+    ...
+  </tr>
+</table>
+
+

BWFC renders the outer table ID but does not generate sub-element IDs:

+
<!-- BWFC output -->
+<table id="Calendar1">
+  <tr>
+    <td>1</td>
+    <td>2</td>
+    ...
+  </tr>
+</table>
+
+

Individual day cells, navigation links, and other internal elements lack the hierarchical IDs that Web Forms generates.

+

Impact

+
    +
  • JavaScript targeting specific day cells by ID (e.g., document.getElementById('Calendar1_Day1_1')) will not work
    • +
  • CSS using #Calendar1_Day1_1 selectors will not match
    • +
  • The outer container ID still works for broad targeting
    • +
+

Workaround

+
    +
  • Use CSS selectors targeting td elements within the Calendar table:
    • +
+
/* Target all day cells */
+#Calendar1 td { ... }
+
+/* Target specific rows */
+#Calendar1 tr:nth-child(3) td { ... }
+
+
    +
  • Add data- attributes via Calendar templates for individual cell targeting
    • +
  • Use positional selectors (:nth-child) for specific cells when needed
    • +
+

Label Element Selection

+

Severity: 🟢 Low — Minimal impact

+

The Label component renders different HTML elements depending on configuration, which matches Web Forms behavior but may surprise developers.

+

What's Different

+ + + + + + + + + + + + + + + + + +
ConfigurationRendered Element
Default (no AssociatedControlID)<span>
With AssociatedControlID set<label for="...">
+

This is actually correct behavior — BWFC matches Web Forms exactly here. The Web Forms Label control always renders as a <span> unless AssociatedControlID is specified, at which point it renders as a <label> element.

+

Impact

+
    +
  • Developers who expect <Label> to always render an HTML <label> element may be surprised
    • +
  • Accessibility audits may flag the <span> output when a <label> was intended
    • +
+

Recommendation

+
    +
  • Always set AssociatedControlID when the label is associated with a form control — this produces the correct <label for="..."> HTML and improves accessibility
    • +
  • If you need an HTML <label> without AssociatedControlID, use a plain <label> element in your Razor markup
    • +
+
@* Renders <span>Name:</span> *@
+<Label Text="Name:" />
+
+@* Renders <label for="txtName">Name:</label> *@
+<Label Text="Name:" AssociatedControlID="txtName" />
+
+

FormView Non-Table Path

+

Severity: 🟢 Low — Expected behavior

+

When RenderOuterTable="false", the FormView renders content without any wrapper element — which means no id attribute is emitted on the output.

+

What's Different

+ + + + + + + + + + + + + + + + + + + + +
SettingWeb FormsBWFC
RenderOuterTable="true" (default)Wraps content in <table> with idWraps content in <table> with id
RenderOuterTable="false"Renders content directly, no wrapperRenders content directly, no wrapper
+

BWFC matches Web Forms here — this is correct behavior. When there is no wrapper element, there is no place to render the id attribute.

+

Impact

+
    +
  • Developers using RenderOuterTable="false" cannot use the ID parameter for CSS/JS targeting on the FormView itself
    • +
  • Content inside the FormView is still targetable via its own IDs or classes
    • +
+

Recommendation

+
    +
  • Use RenderOuterTable="true" (the default) if you need the id attribute for CSS or JavaScript targeting
    • +
  • When using RenderOuterTable="false", target content elements directly rather than the FormView container
    • +
+

ID Rendering Coverage

+

BWFC supports id rendering via the ID parameter across a wide range of controls. The rendered id attribute uses the value from the ClientID property, which follows the Web Forms naming hierarchy.

+

Controls Supporting ID Rendering

+

The following controls emit id="@ClientID" when the ID parameter is set:

+ + + + + + + + + + + + + + + + + +
CategoryControls
Editor ControlsButton, BulletedList, Calendar, CheckBox, DropDownList, FileUpload, HiddenField, Label, LinkButton, Panel, TextBox
Data ControlsDataGrid, DataList, DetailsView, FormView, GridView
+

ClientIDMode Support

+

All components support ClientIDMode matching the Web Forms behavior:

+ + + + + + + + + + + + + + + + + + + + + +
ModeBehavior
StaticID is rendered exactly as specified
PredictableID uses a predictable pattern based on parent hierarchy
AutoIDID includes the full naming container path (e.g., Parent_Child)
+

Notable Exception: ListView

+

The ListView component cannot render a root-level ID because it uses a developer-provided LayoutTemplate for its outer markup. The ListView has no single root element that it controls — the outer structure is entirely defined by the template.

+

To add an ID to a ListView, include it in your LayoutTemplate:

+
<ListView DataSource="@Items">
+    <LayoutTemplate>
+        <div id="myListView">
+            <PlaceHolder ID="itemPlaceholder" />
+        </div>
+    </LayoutTemplate>
+    <ItemTemplate Context="item">
+        <div>@item.Name</div>
+    </ItemTemplate>
+</ListView>
+
+

Opt-in Behavior

+

ID rendering is opt-in — the id attribute is only emitted when the developer explicitly sets the ID parameter on a component. Components without an ID render no id attribute in the HTML output.

+

For comprehensive details, see the ID Rendering documentation.

+

General Recommendations

+

CSS Targeting

+

When migrating CSS that targets Web Forms output:

+
    +
  1. Prefer class selectors over element/structural selectors — classes survive DOM restructuring
    2. +
  2. Avoid deep descendant selectors like table > tbody > tr > td > div — these are fragile
    3. +
  3. Use the rendered ID where available — BWFC generates matching IDs on most controls
    4. +
  4. Test with browser DevTools — inspect the rendered HTML to verify selectors match
    5. +
+
/* Fragile — depends on exact DOM structure */
+#GridView1 > table > tbody > tr:first-child > th { font-weight: bold; }
+
+/* Resilient — targets semantic class */
+#GridView1 .header-row { font-weight: bold; }
+
+

JavaScript Targeting

+

When migrating JavaScript that targets Web Forms output:

+
    +
  1. Use document.getElementById() with the control's ID — this is the most reliable approach
    2. +
  2. Add data- attributes in templates for elements that lack IDs
    3. +
  3. Avoid DOM traversal (parentNode, nextSibling) — the structural nesting may differ
    4. +
  4. Use querySelector with class or attribute selectors as a fallback
    5. +
+
// Reliable — uses rendered ID
+var grid = document.getElementById('GridView1');
+
+// Reliable — uses data attribute
+var items = document.querySelectorAll('[data-item-id]');
+
+// Fragile — assumes specific DOM depth
+var cell = element.parentNode.parentNode.firstChild;
+
+

Verifying Fidelity

+

To compare BWFC output against Web Forms output for a specific control:

+
    +
  1. Render the control in both environments with the same properties
    2. +
  2. Compare the HTML output using a diff tool
    3. +
  3. Check that your CSS selectors match both outputs
    4. +
  4. Verify JavaScript interactions work against both DOMs
    5. +
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/NavigationControls/HyperLink/index.html b/site/NavigationControls/HyperLink/index.html new file mode 100644 index 000000000..24db94830 --- /dev/null +++ b/site/NavigationControls/HyperLink/index.html @@ -0,0 +1,4932 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + HyperLink - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

HyperLink

+ +

It may seem strange that we have a HyperLink component when there already is an HTML anchor and Blazor has features that enable C# interactions with that link, 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.hyperlink?view=netframework-4.8

+

Blazor Features Supported

+

Core Properties

+
    +
  • NavigateUrl - the URL to link when HyperLink component is clicked
    • +
  • Text - the text content of the HyperLink component
    • +
  • Target - the target window or frame in which to display the Web page content linked to when the HyperLink component is clicked (e.g., "_blank", "_self", "_parent", "_top")
    • +
  • ToolTip - displays a tooltip on hover (rendered as the title attribute)
    • +
+

Styling Properties

+
    +
  • BackColor - background color of the hyperlink
    • +
  • ForeColor - text color of the hyperlink
    • +
  • BorderColor - border color
    • +
  • BorderStyle - border style (NotSet, None, Dotted, Dashed, Solid, Double, Groove, Ridge, Inset, Outset)
    • +
  • BorderWidth - border width
    • +
  • CssClass - CSS class name to apply to the hyperlink
    • +
  • Height - height of the hyperlink
    • +
  • Width - width of the hyperlink
    • +
+

Font Properties

+
    +
  • Font-Bold - bold text
    • +
  • Font-Italic - italic text
    • +
  • Font-Names - font family names
    • +
  • Font-Overline - overline text decoration
    • +
  • Font-Size - font size
    • +
  • Font-Strikeout - strikethrough text decoration
    • +
  • Font-Underline - underline text decoration
    • +
+

Other Properties

+
    +
  • Visible - whether the hyperlink is visible (default: true)
    • +
+

Event Handlers

+
    +
  • OnDataBinding - event handler for data binding
    • +
  • OnInit - event handler triggered at initialization
    • +
  • OnLoad - event handler triggered after component loads
    • +
  • OnPreRender - event handler triggered before rendering
    • +
  • OnUnload - event handler triggered when component unloads
    • +
  • OnDisposed - event handler triggered when component is disposed
    • +
+

WebForms Features Not Supported

+
    +
  • ImageUrl - The Blazor HyperLink component does not support image links. Use the Image component wrapped in an anchor tag instead.
    • +
  • AccessKey - Not supported in Blazor
    • +
  • Enabled - While the property exists for compatibility, it does not affect the hyperlink's behavior (the link is not disabled)
    • +
  • TabIndex - While the property exists in the base class, it is not rendered on the hyperlink element
    • +
  • EnableTheming - Theming is not available in Blazor
    • +
  • EnableViewState - ViewState is supported for compatibility but this parameter does nothing
    • +
  • SkinID - Theming is not available in Blazor
    • +
+

Syntax Comparison

+
+
+
+
<asp:HyperLink ID="lnkExample" 
+    NavigateUrl="https://example.com" 
+    Text="Visit Example" 
+    Target="_blank"
+    ToolTip="Click to visit example.com"
+    CssClass="btn btn-link"
+    runat="server" />
+
+
+
+
<HyperLink NavigateUrl="https://example.com" 
+    Text="Visit Example" 
+    Target="_blank"
+    ToolTip="Click to visit example.com"
+    CssClass="btn btn-link" />
+
+
+
+
+

WebForms Syntax Reference

+
<asp:HyperLink
+    AccessKey="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    ImageUrl="uri"
+    NavigateUrl="uri"
+    OnDataBinding="DataBinding event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    runat="server"
+    SkinID="string"
+    Style="string"
+    TabIndex="integer"
+    Target="string|_blank|_parent|_search|_self|_top"
+    Text="string"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+

Usage Examples

+

Blazor with Styling

+
<HyperLink NavigateUrl="/products" 
+    Text="View Products" 
+    ForeColor="#0066cc"
+    Font-Bold="true"
+    Font-Size="14px" />
+
+

Blazor without NavigateUrl (renders as plain anchor)

+
<HyperLink Text="Inactive Link" 
+    ToolTip="This link has no URL" />
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/NavigationControls/ImageMap/index.html b/site/NavigationControls/ImageMap/index.html new file mode 100644 index 000000000..7d12f0e11 --- /dev/null +++ b/site/NavigationControls/ImageMap/index.html @@ -0,0 +1,5300 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ImageMap - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ImageMap

+

The ImageMap component displays an image with defined clickable hot spot regions. Each hot spot can navigate to a URL or trigger a server-side event when clicked, emulating the ASP.NET Web Forms ImageMap control. This is useful for interactive images like site maps, diagrams, or region selectors.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.imagemap?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • ImageUrl — URL of the image to display
    • +
  • AlternateText — alternate text when the image is unavailable
    • +
  • DescriptionUrl — URL to a detailed description for accessibility
    • +
  • ImageAlign — alignment of the image relative to other elements (NotSet, Left, Right, Baseline, Top, Middle, Bottom, AbsBottom, AbsMiddle, TextTop)
    • +
  • ToolTip — tooltip text displayed on hover
    • +
  • GenerateEmptyAlternateText — generates an empty alt="" for decorative images
    • +
  • HotSpotMode — default behavior for hot spots: Navigate, PostBack, Inactive, or NotSet
    • +
  • Target — default target window/frame for navigation links
    • +
  • HotSpots — collection of HotSpot objects defining clickable regions
    • +
  • OnClick — event raised when a hot spot in PostBack mode is clicked, providing ImageMapEventArgs
    • +
  • Visible — controls visibility
    • +
+

Hot Spot Types

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeShapePropertiesCoordinates Format
RectangleHotSpotrectLeft, Top, Right, Bottomleft,top,right,bottom
CircleHotSpotcircleX, Y, Radiusx,y,radius
PolygonHotSpotpolyCoordinates (string)x1,y1,x2,y2,...
+

HotSpot Base Properties

+

All hot spot types share these properties:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
AlternateTextstringAlt text for the hot spot area
HotSpotModeHotSpotModeBehavior override (NotSet inherits from parent ImageMap)
NavigateUrlstringURL to navigate to (when mode is Navigate)
PostBackValuestringValue passed in event args (when mode is PostBack)
TargetstringTarget window/frame for navigation
TabIndexshortTab order of the hot spot
AccessKeystringKeyboard shortcut for the hot spot
+

Web Forms Features NOT Supported

+
    +
  • Style properties (BackColor, ForeColor, etc.) — Not applicable to the <img> and <map> elements; use CSS on a wrapper element
    • +
  • EnableTheming/SkinID — ASP.NET theming is not available in Blazor
    • +
  • Lifecycle events (OnDataBinding, OnInit, etc.) — Use Blazor lifecycle methods instead
    • +
+

Syntax Comparison

+
+
+
+
<asp:ImageMap
+    ID="string"
+    ImageUrl="uri"
+    AlternateText="string"
+    HotSpotMode="Navigate|PostBack|Inactive|NotSet"
+    OnClick="Click event handler"
+    Target="string"
+    ToolTip="string"
+    runat="server">
+    <asp:RectangleHotSpot
+        AlternateText="string"
+        Bottom="integer"
+        HotSpotMode="Navigate|PostBack|Inactive|NotSet"
+        Left="integer"
+        NavigateUrl="uri"
+        PostBackValue="string"
+        Right="integer"
+        Target="string"
+        Top="integer" />
+    <asp:CircleHotSpot
+        AlternateText="string"
+        HotSpotMode="Navigate|PostBack|Inactive|NotSet"
+        NavigateUrl="uri"
+        PostBackValue="string"
+        Radius="integer"
+        Target="string"
+        X="integer"
+        Y="integer" />
+    <asp:PolygonHotSpot
+        AlternateText="string"
+        Coordinates="string"
+        HotSpotMode="Navigate|PostBack|Inactive|NotSet"
+        NavigateUrl="uri"
+        PostBackValue="string"
+        Target="string" />
+</asp:ImageMap>
+
+
+
+
@using BlazorWebFormsComponents
+@using BlazorWebFormsComponents.Enums
+
+<ImageMap ImageUrl="/images/map.png"
+          AlternateText="Site Map"
+          HotSpotMode="HotSpotMode.Navigate"
+          HotSpots="@hotSpots" />
+
+@code {
+    private List<HotSpot> hotSpots = new List<HotSpot>
+    {
+        new RectangleHotSpot
+        {
+            Top = 0, Left = 0, Bottom = 100, Right = 200,
+            NavigateUrl = "/page1",
+            AlternateText = "Region 1"
+        },
+        new CircleHotSpot
+        {
+            X = 300, Y = 150, Radius = 50,
+            NavigateUrl = "/page2",
+            AlternateText = "Region 2"
+        }
+    };
+}
+
+
+
+
+

Blazor Usage Examples

+ +
@using BlazorWebFormsComponents
+@using BlazorWebFormsComponents.Enums
+
+<ImageMap ImageUrl="/images/floorplan.png"
+          AlternateText="Office Floor Plan"
+          HotSpotMode="HotSpotMode.Navigate"
+          HotSpots="@hotSpots" />
+
+@code {
+    private List<HotSpot> hotSpots = new List<HotSpot>
+    {
+        new RectangleHotSpot
+        {
+            Left = 0, Top = 0, Right = 200, Bottom = 150,
+            NavigateUrl = "/rooms/conference-a",
+            AlternateText = "Conference Room A"
+        },
+        new CircleHotSpot
+        {
+            X = 300, Y = 200, Radius = 50,
+            NavigateUrl = "/rooms/lobby",
+            AlternateText = "Lobby"
+        }
+    };
+}
+
+

PostBack Hot Spots with Event Handling

+
@using BlazorWebFormsComponents
+@using BlazorWebFormsComponents.Enums
+
+<ImageMap ImageUrl="/images/regions.png"
+          AlternateText="Select a Region"
+          HotSpotMode="HotSpotMode.PostBack"
+          OnClick="HandleRegionClick"
+          HotSpots="@regions" />
+
+<p>Selected region: @selectedRegion</p>
+
+@code {
+    private string selectedRegion = "None";
+
+    private List<HotSpot> regions = new List<HotSpot>
+    {
+        new PolygonHotSpot
+        {
+            Coordinates = "10,10,100,10,100,100,10,100",
+            PostBackValue = "North",
+            AlternateText = "North Region"
+        },
+        new RectangleHotSpot
+        {
+            Left = 110, Top = 10, Right = 200, Bottom = 100,
+            PostBackValue = "South",
+            AlternateText = "South Region"
+        }
+    };
+
+    void HandleRegionClick(ImageMapEventArgs args)
+    {
+        selectedRegion = args.PostBackValue;
+    }
+}
+
+

Mixed Hot Spot Modes

+

Individual hot spots can override the parent HotSpotMode:

+
<ImageMap ImageUrl="/images/map.png"
+          AlternateText="Interactive Map"
+          HotSpotMode="HotSpotMode.Navigate"
+          OnClick="HandleClick"
+          HotSpots="@mixedSpots" />
+
+@code {
+    private List<HotSpot> mixedSpots = new List<HotSpot>
+    {
+        new RectangleHotSpot
+        {
+            Left = 0, Top = 0, Right = 100, Bottom = 50,
+            NavigateUrl = "/page1",
+            AlternateText = "Navigate to Page 1"
+        },
+        new CircleHotSpot
+        {
+            X = 200, Y = 100, Radius = 30,
+            HotSpotMode = HotSpotMode.PostBack,
+            PostBackValue = "circle-clicked",
+            AlternateText = "Click for action"
+        },
+        new RectangleHotSpot
+        {
+            Left = 300, Top = 0, Right = 400, Bottom = 50,
+            HotSpotMode = HotSpotMode.Inactive,
+            AlternateText = "Disabled region"
+        }
+    };
+
+    void HandleClick(ImageMapEventArgs args)
+    {
+        // Only PostBack hot spots trigger this event
+    }
+}
+
+ +
<ImageMap ImageUrl="/images/partners.png"
+          AlternateText="Our Partners"
+          HotSpotMode="HotSpotMode.Navigate"
+          Target="_blank"
+          HotSpots="@partnerSpots" />
+
+@code {
+    private List<HotSpot> partnerSpots = new List<HotSpot>
+    {
+        new RectangleHotSpot
+        {
+            Left = 0, Top = 0, Right = 150, Bottom = 80,
+            NavigateUrl = "https://partner1.example.com",
+            AlternateText = "Partner 1"
+        },
+        new RectangleHotSpot
+        {
+            Left = 160, Top = 0, Right = 310, Bottom = 80,
+            NavigateUrl = "https://partner2.example.com",
+            AlternateText = "Partner 2",
+            Target = "_self"  // Override: open in same window
+        }
+    };
+}
+
+

HTML Output

+

Blazor Input: +

<ImageMap ImageUrl="/images/map.png"
+          AlternateText="Site Map"
+          HotSpotMode="HotSpotMode.Navigate"
+          HotSpots="@spots" />
+

+

Rendered HTML: +

<img src="/images/map.png" usemap="#ImageMap_1" alt="Site Map" />
+
+<map name="ImageMap_1">
+    <area shape="rect" coords="0,0,200,150" href="/page1" alt="Page 1" />
+    <area shape="circle" coords="300,200,50" href="/page2" alt="Page 2" />
+    <area shape="poly" coords="10,10,100,10,55,80" href="/page3" alt="Page 3" />
+</map>
+

+

HotSpotMode Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ModeBehavior
NotSetInherits the mode from the parent ImageMap.HotSpotMode
NavigateNavigates to the URL specified in NavigateUrl
PostBackRaises the OnClick event with ImageMapEventArgs containing the PostBackValue
InactiveRenders the area with nohref; no click action
+

Migration Notes

+

When migrating from Web Forms to Blazor:

+
    +
  1. Remove asp: prefix — Change <asp:ImageMap> to <ImageMap> and <asp:RectangleHotSpot> to C# objects
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Convert child elements to C# objects — Web Forms used declarative child elements for hot spots. In Blazor, create List<HotSpot> in your @code block
    4. +
  4. Update event handler syntax — Change OnClick="ImageMap1_Click" to OnClick="HandleClick"
    5. +
  5. Event args change — The handler receives ImageMapEventArgs directly (no object sender parameter)
    6. +
+

Before (Web Forms)

+
<asp:ImageMap ID="imgMap1" 
+              ImageUrl="~/images/map.png"
+              HotSpotMode="PostBack"
+              OnClick="imgMap1_Click"
+              runat="server">
+    <asp:RectangleHotSpot 
+        Top="0" Left="0" Bottom="100" Right="200"
+        PostBackValue="region1"
+        AlternateText="Region 1" />
+    <asp:CircleHotSpot 
+        X="300" Y="150" Radius="50"
+        PostBackValue="region2"
+        AlternateText="Region 2" />
+</asp:ImageMap>
+
+
protected void imgMap1_Click(object sender, ImageMapEventArgs e)
+{
+    string region = e.PostBackValue;
+    lblResult.Text = "You clicked: " + region;
+}
+
+

After (Blazor)

+
@using BlazorWebFormsComponents
+@using BlazorWebFormsComponents.Enums
+
+<ImageMap ImageUrl="/images/map.png"
+          HotSpotMode="HotSpotMode.PostBack"
+          OnClick="HandleClick"
+          HotSpots="@hotSpots" />
+
+<Label Text="@resultText" />
+
+@code {
+    private string resultText = "";
+
+    private List<HotSpot> hotSpots = new List<HotSpot>
+    {
+        new RectangleHotSpot
+        {
+            Top = 0, Left = 0, Bottom = 100, Right = 200,
+            PostBackValue = "region1",
+            AlternateText = "Region 1"
+        },
+        new CircleHotSpot
+        {
+            X = 300, Y = 150, Radius = 50,
+            PostBackValue = "region2",
+            AlternateText = "Region 2"
+        }
+    };
+
+    void HandleClick(ImageMapEventArgs args)
+    {
+        resultText = "You clicked: " + args.PostBackValue;
+    }
+}
+
+
+

Declarative vs. Programmatic Hot Spots

+

In Web Forms, hot spots were declared as child elements in markup. In Blazor, hot spots are defined as C# objects in a List<HotSpot> and passed via the HotSpots parameter. This is a structural difference, but the rendered HTML output is identical.

+
+

See Also

+
    +
  • Image — The basic Image component
    • +
  • ImageButton — A clickable image button
    • +
  • HyperLink — Simple link navigation
    • +
  • Menu — Hierarchical navigation menu
    • +
  • SiteMapPath — Breadcrumb navigation path
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/NavigationControls/Menu/index.html b/site/NavigationControls/Menu/index.html new file mode 100644 index 000000000..59650e512 --- /dev/null +++ b/site/NavigationControls/Menu/index.html @@ -0,0 +1,5254 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Menu - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Menu

+

The Menu component is meant to emulate the asp:Menu control in markup and is defined in the System.Web.UI.WebControls.Menu class

+

Usage Notes | Syntax Comparison | Examples

+

Features supported in Blazor

+
    +
  • Simple static menu, as shown in the ASP.NET example
    • +
  • Simple databinding to a Sitemap as shown in the ASP.NET example
    • +
  • Selection and Events - MenuItemClick event, SelectedItem, SelectedValue
    • +
  • Orientation - Horizontal or Vertical layout
    • +
  • Style Sub-Components - StaticMenuItemStyle, DynamicMenuItemStyle, StaticHoverStyle, DynamicHoverStyle, DynamicSelectedStyle, DynamicMenuStyle
    • +
  • Navigation Properties - Target, MaximumDynamicDisplayLevels, SkipLinkText
    • +
+
Back to top
+

Usage Notes

+
    +
  • Databinding only works with sitemap. Sitemap must be loaded and set as an XML document on DataSource
    • +
+
Back to top
+

Syntax Comparison

+
+
+
+
<asp:Menu
+    AccessKey="string"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    DataSource="string"
+    DataSourceID="string"
+    DisappearAfter="integer"
+    DynamicBottomSeparatorImageUrl="uri"
+    DynamicEnableDefaultPopOutImage="True|False"
+    DynamicHorizontalOffset="integer"
+    DynamicItemFormatString="string"
+    DynamicPopOutImageTextFormatString="string"
+    DynamicPopOutImageUrl="uri"
+    DynamicTopSeparatorImageUrl="uri"
+    DynamicVerticalOffset="integer"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+        Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    ItemWrap="True|False"
+    MaximumDynamicDisplayLevels="integer"
+    OnDataBinding="DataBinding event handler"
+    OnDataBound="DataBound event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnMenuItemClick="MenuItemClick event handler"
+    OnMenuItemDataBound="MenuItemDataBound event handler"
+    OnPreRender="PreRender event handler"
+    OnUnload="Unload event handler"
+    Orientation="Horizontal|Vertical"
+    PathSeparator="string"
+    runat="server"
+    ScrollDownImageUrl="uri"
+    ScrollDownText="string"
+    ScrollUpImageUrl="uri"
+    ScrollUpText="string"
+    SkinID="string"
+    SkipLinkText="string"
+    StaticBottomSeparatorImageUrl="uri"
+    StaticDisplayLevels="integer"
+    StaticEnableDefaultPopOutImage="True|False"
+    StaticItemFormatString="string"
+    StaticPopOutImageTextFormatString="string"
+    StaticPopOutImageUrl="uri"
+    StaticSubMenuIndent="size"
+    StaticTopSeparatorImageUrl="uri"
+    Style="string"
+    TabIndex="integer"
+    Target="string"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size" >
+    <!-- DataBindings, Styles, Items, etc. -->
+</asp:Menu>
+
+
+
+
<Menu id="NavigationMenu"
+      DisappearAfter="2000"
+      StaticDisplayLevels="2"
+      StaticSubmenuIndent="10"
+      orientation="Vertical"
+      font-names="Arial"
+      target="_blank">
+
+    <StaticMenuItemStyle BackColor="@("LightSteelBlue")"
+                         ForeColor="@("Black")" />
+    <StaticHoverStyle BackColor="WebColor.LightSkyBlue" />
+    <DynamicMenuItemStyle BackColor="WebColor.Black"
+                          ForeColor="WebColor.Silver" />
+    <DynamicHoverStyle BackColor="WebColor.LightSkyBlue"
+                       ForeColor="WebColor.Black" />
+    <DynamicSelectedStyle BackColor="WebColor.PapayaWhip"
+                          ForeColor="WebColor.SteelBlue" />
+
+    <Items>
+        <MenuItem navigateurl="Home.aspx"
+                  text="Home"
+                  tooltip="Home">
+            <MenuItem text="Music" tooltip="Music">
+                <MenuItem navigateurl="Classical.aspx"
+                          text="Classical"
+                          tooltip="Classical" />
+                <MenuItem navigateurl="Rock.aspx"
+                          text="Rock"
+                          tooltip="Rock" />
+                <MenuItem navigateurl="Jazz.aspx"
+                          text="Jazz"
+                          tooltip="Jazz" />
+            </MenuItem>
+            <MenuItem navigateurl="Movies.aspx" text="Movies" tooltip="Movies">
+                <MenuItem navigateurl="Action.aspx"
+                          text="Action"
+                          tooltip="Action" />
+                <MenuItem navigateurl="Drama.aspx"
+                          text="Drama"
+                          tooltip="Drama" />
+                <MenuItem navigateurl="Musical.aspx"
+                          text="Musical"
+                          tooltip="Musical" />
+            </MenuItem>
+        </MenuItem>
+    </Items>
+
+</Menu>
+
+
+
+
+

Examples

+

Basic Menu with Click Events

+
<Menu Orientation="Vertical"
+      MenuItemClick="HandleMenuClick">
+    <Items>
+        <MenuItem Text="Home" Value="home" NavigateUrl="/" />
+        <MenuItem Text="Products" Value="products">
+            <MenuItem Text="Electronics" Value="electronics" NavigateUrl="/electronics" />
+            <MenuItem Text="Clothing" Value="clothing" NavigateUrl="/clothing" />
+        </MenuItem>
+        <MenuItem Text="About" Value="about" NavigateUrl="/about" />
+    </Items>
+</Menu>
+
+<p>Clicked: @clickedItem</p>
+
+@code {
+    private string clickedItem = "";
+
+    private void HandleMenuClick(MenuEventArgs e)
+    {
+        clickedItem = e.Item.Text;
+    }
+}
+
+

Horizontal Menu

+
<Menu Orientation="Horizontal"
+      SkipLinkText="Skip main navigation"
+      Target="_self">
+    <Items>
+        <MenuItem Text="Home" NavigateUrl="/" />
+        <MenuItem Text="Products" NavigateUrl="/products" />
+        <MenuItem Text="Services" NavigateUrl="/services" />
+        <MenuItem Text="Contact" NavigateUrl="/contact" />
+    </Items>
+    <StaticMenuItemStyle BackColor="@("SteelBlue")" ForeColor="@("White")" />
+    <StaticHoverStyle BackColor="@("LightSteelBlue")" ForeColor="@("Black")" />
+</Menu>
+
+ +
<Menu Orientation="Vertical"
+      MaximumDynamicDisplayLevels="3"
+      StaticDisplayLevels="2">
+    <Items>
+        <MenuItem Text="File" Value="file">
+            <MenuItem Text="New" Value="new" />
+            <MenuItem Text="Open" Value="open" />
+            <MenuItem Text="Save" Value="save" />
+        </MenuItem>
+        <MenuItem Text="Edit" Value="edit">
+            <MenuItem Text="Cut" Value="cut" />
+            <MenuItem Text="Copy" Value="copy" />
+            <MenuItem Text="Paste" Value="paste" />
+        </MenuItem>
+    </Items>
+    <StaticMenuItemStyle BackColor="@("LightSteelBlue")" ForeColor="@("Black")" />
+    <DynamicMenuItemStyle BackColor="WebColor.Black" ForeColor="WebColor.Silver" />
+    <DynamicHoverStyle BackColor="WebColor.LightSkyBlue" ForeColor="WebColor.Black" />
+    <DynamicSelectedStyle BackColor="WebColor.PapayaWhip" ForeColor="WebColor.SteelBlue" />
+</Menu>
+
+

Data Binding with SiteMap

+
@using System.Xml
+
+<Menu DataSource="@sitemapXml"
+      Orientation="Horizontal"
+      StaticDisplayLevels="2">
+    <DataBindings>
+        <MenuItemBinding DataMember="siteMapNode"
+                         TextField="title"
+                         NavigateUrlField="url" />
+    </DataBindings>
+</Menu>
+
+@code {
+    private XmlDocument sitemapXml;
+
+    protected override void OnInitialized()
+    {
+        sitemapXml = new XmlDocument();
+        sitemapXml.LoadXml(@"
+            <siteMap>
+                <siteMapNode title='Home' url='/'>
+                    <siteMapNode title='Products' url='/products' />
+                    <siteMapNode title='About' url='/about' />
+                </siteMapNode>
+            </siteMap>");
+    }
+}
+
+

Selection and Events Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property/EventTypeDefaultDescription
MenuItemClickEventCallback<MenuEventArgs>—Fires when a menu item is clicked.
MenuItemDataBoundEventCallback<MenuEventArgs>—Fires when a menu item is data-bound.
SelectedItemMenuItemnullRead-only. The currently selected menu item.
SelectedValuestringnullRead-only. The Value of the selected menu item.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
OrientationOrientationVerticalMenu layout direction (Horizontal or Vertical).
TargetstringnullDefault target frame for navigation links.
MaximumDynamicDisplayLevelsint3Max depth of dynamically displayed submenus.
SkipLinkTextstring"Skip Navigation Links"Accessibility skip-link text for screen readers.
StaticDisplayLevelsint1Number of menu levels displayed statically.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
TextstringDisplay text for the menu item.
ValuestringValue associated with the menu item.
NavigateUrlstringURL to navigate to when clicked.
ToolTipstringTooltip text on hover.
TargetstringTarget frame (falls back to Menu.Target).
ChildContentRenderFragmentNested child MenuItem components.
+

Style Sub-Components Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentApplied To
<StaticMenuItemStyle>Static (always-visible) menu items
<StaticHoverStyle>Static menu items on hover
<DynamicMenuItemStyle>Dynamically displayed submenu items
<DynamicMenuStyle>Dynamic submenu container
<DynamicHoverStyle>Dynamic menu items on hover
<DynamicSelectedStyle>Selected item in dynamic menus
+

All style components support BackColor, ForeColor, CssClass, BorderColor, BorderStyle, BorderWidth, Font, Height, and Width properties.

+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/NavigationControls/SiteMapPath/index.html b/site/NavigationControls/SiteMapPath/index.html new file mode 100644 index 000000000..18484eba6 --- /dev/null +++ b/site/NavigationControls/SiteMapPath/index.html @@ -0,0 +1,5100 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + SiteMapPath - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

SiteMapPath

+

The SiteMapPath component displays a breadcrumb navigation path showing the current page's location within a site hierarchy. It helps users understand where they are in your application and provides quick navigation back to parent pages.

+

Original Microsoft implementation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.sitemappath?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • PathSeparator - Custom separator string between nodes (default: " > ")
    • +
  • PathSeparatorTemplate - Custom template for rendering separators
    • +
  • PathDirection - RootToCurrent or CurrentToRoot ordering
    • +
  • RenderCurrentNodeAsLink - Whether the current page is clickable
    • +
  • ShowToolTips - Display node descriptions as tooltips
    • +
  • ParentLevelsDisplayed - Limit breadcrumb depth (-1 for all)
    • +
  • CurrentNodeTemplate - Custom template for current page node
    • +
  • NodeTemplate - Custom template for ancestor nodes
    • +
  • RootNodeTemplate - Custom template for the root/home node
    • +
  • Style properties - CurrentNodeStyle, NodeStyle, RootNodeStyle, PathSeparatorStyle
    • +
  • Events - ItemCreated and ItemDataBound for node lifecycle callbacks
    • +
+

Blazor Notes

+

Unlike Web Forms, which uses a Web.sitemap XML file with SiteMapDataSource, the Blazor implementation requires you to provide the site hierarchy programmatically via the SiteMapProvider property. This gives you more flexibility to build navigation hierarchies dynamically from databases, configuration, or other sources.

+

The SiteMapNode class provides a simple way to build hierarchies:

+
var root = new SiteMapNode("Home", "/");
+var products = new SiteMapNode("Products", "/products", "Browse our products");
+root.AddChild(products);
+
+

Web Forms Features NOT Supported

+
    +
  • SiteMapDataSource - Not supported; provide a SiteMapNode hierarchy directly
    • +
  • Web.sitemap XML file - Not supported; build the hierarchy in code
    • +
  • Provider - The SiteMapProvider property accepts a SiteMapNode root, not a provider name
    • +
  • SkipLinkText - Accessibility skip link not implemented
    • +
+

Syntax Comparison

+
+
+
+
<asp:SiteMapPath
+    CurrentNodeStyle-BackColor="Yellow"
+    CurrentNodeTemplate="..."
+    ID="SiteMapPath1"
+    NodeStyle-ForeColor="Blue"
+    NodeTemplate="..."
+    ParentLevelsDisplayed="-1"
+    PathDirection="RootToCurrent"
+    PathSeparator=" > "
+    PathSeparatorStyle-Font-Bold="true"
+    PathSeparatorTemplate="..."
+    RenderCurrentNodeAsLink="false"
+    RootNodeStyle-Font-Bold="true"
+    RootNodeTemplate="..."
+    ShowToolTips="true"
+    SiteMapProvider="AspNetXmlSiteMapProvider"
+    SkipLinkText=""
+    runat="server" />
+
+
+
+
<SiteMapPath
+    CurrentUrl="@CurrentPage"
+    ParentLevelsDisplayed="-1"
+    PathDirection="PathDirection.RootToCurrent"
+    PathSeparator=" > "
+    RenderCurrentNodeAsLink="false"
+    ShowToolTips="true"
+    SiteMapProvider="@SiteMap" />
+
+
+
+
+

Usage Notes

+
    +
  1. Build your site map in code - Create a SiteMapNode hierarchy that represents your site structure
    2. +
  2. Provide the current URL - Set CurrentUrl to match against the site map nodes
    3. +
  3. URL matching is flexible - The component normalizes URLs, handling leading slashes and query strings
    4. +
  4. Templates override default rendering - When you provide a template, you're responsible for all markup including links
    5. +
+

Examples

+

Basic Usage

+
@* Basic breadcrumb navigation *@
+<SiteMapPath SiteMapProvider="@SiteMap" CurrentUrl="@CurrentUrl" />
+
+@code {
+    private string CurrentUrl = "/products/electronics";
+
+    private SiteMapNode SiteMap = BuildSiteMap();
+
+    private static SiteMapNode BuildSiteMap()
+    {
+        var root = new SiteMapNode("Home", "/");
+        var products = new SiteMapNode("Products", "/products", "Browse our catalog");
+        var electronics = new SiteMapNode("Electronics", "/products/electronics");
+
+        root.AddChild(products);
+        products.AddChild(electronics);
+
+        return root;
+    }
+}
+
+

Custom Separator

+
@* Using a custom separator *@
+<SiteMapPath 
+    SiteMapProvider="@SiteMap" 
+    CurrentUrl="/products" 
+    PathSeparator=" / " />
+
+@* Using a template for the separator *@
+<SiteMapPath SiteMapProvider="@SiteMap" CurrentUrl="/products">
+    <PathSeparatorTemplate>
+        <span class="mx-2">→</span>
+    </PathSeparatorTemplate>
+</SiteMapPath>
+
+ +
@* Make the current page clickable *@
+<SiteMapPath 
+    SiteMapProvider="@SiteMap" 
+    CurrentUrl="/products" 
+    RenderCurrentNodeAsLink="true" />
+
+

Limiting Parent Levels

+
@* Only show 2 parent levels *@
+<SiteMapPath 
+    SiteMapProvider="@SiteMap" 
+    CurrentUrl="/products/electronics/phones/iphone" 
+    ParentLevelsDisplayed="2" />
+@* Renders: Electronics > Phones > iPhone (skips Home and Products) *@
+
+

Custom Templates

+
@* Full template customization *@
+<SiteMapPath SiteMapProvider="@SiteMap" CurrentUrl="/products/electronics">
+    <RootNodeTemplate Context="node">
+        <a href="@node.Url" class="text-primary">🏠 @node.Title</a>
+    </RootNodeTemplate>
+    <NodeTemplate Context="node">
+        <a href="@node.Url" class="text-secondary">@node.Title</a>
+    </NodeTemplate>
+    <CurrentNodeTemplate Context="node">
+        <strong class="text-dark">📍 @node.Title</strong>
+    </CurrentNodeTemplate>
+    <PathSeparatorTemplate>
+        <span class="text-muted mx-1">/</span>
+    </PathSeparatorTemplate>
+</SiteMapPath>
+
+

Reverse Path Direction

+
@* Show current page first, then parents *@
+<SiteMapPath 
+    SiteMapProvider="@SiteMap" 
+    CurrentUrl="/products/electronics" 
+    PathDirection="PathDirection.CurrentToRoot" />
+@* Renders: Electronics > Products > Home *@
+
+

Events

+

ItemCreated

+

Fires when a breadcrumb node item is created during rendering. The callback receives a SiteMapNodeItemEventArgs with an Item property referencing the SiteMapNode.

+
<SiteMapPath SiteMapProvider="@SiteMap"
+             CurrentUrl="/products"
+             ItemCreated="HandleItemCreated" />
+
+@code {
+    private void HandleItemCreated(SiteMapNodeItemEventArgs e)
+    {
+        Console.WriteLine($"Node created: {e.Item.Title}");
+    }
+}
+
+

ItemDataBound

+

Fires when a breadcrumb node item is bound to its data source. Useful for customizing node display dynamically.

+
<SiteMapPath SiteMapProvider="@SiteMap"
+             CurrentUrl="/products"
+             ItemDataBound="HandleItemDataBound" />
+
+@code {
+    private void HandleItemDataBound(SiteMapNodeItemEventArgs e)
+    {
+        Console.WriteLine($"Node data-bound: {e.Item.Title} → {e.Item.Url}");
+    }
+}
+
+

SiteMapNodeItemEventArgs

+ + + + + + + + + + + + + + + +
PropertyTypeDescription
ItemSiteMapNodeThe site map node associated with the event
+

See Also

+
    +
  • Menu — Hierarchical navigation menu
    • +
  • TreeView — Tree-style hierarchical navigation
    • +
  • HyperLink — Simple link navigation
    • +
  • ImageMap — Image with clickable regions
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/NavigationControls/TreeView/index.html b/site/NavigationControls/TreeView/index.html new file mode 100644 index 000000000..42e6a8d16 --- /dev/null +++ b/site/NavigationControls/TreeView/index.html @@ -0,0 +1,5800 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TreeView - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

TreeView

+ +

The TreeView component is meant to emulate the asp:TreeView control in markup and is defined in the System.Web.UI.WebControls.TreeView class

+

Features supported in Blazor

+
    +
  • Static Tree Nodes
    • +
  • Checkbox display
    • +
  • TreeNode expand and collapse events
    • +
  • TreeNode checkbox checked / unchecked events
    • +
  • XmlDocument databinding
    • +
  • SiteMap databinding as an XmlDocument
    • +
  • Databinding events
    • +
  • Accessibility features (see below)
    • +
  • Node-Level Styles - NodeStyle, HoverNodeStyle, LeafNodeStyle, ParentNodeStyle, RootNodeStyle, SelectedNodeStyle
    • +
  • Selection - SelectedNode, SelectedValue, SelectedNodeChanged event
    • +
  • +

    Expand/Collapse - ExpandAll(), CollapseAll(), ExpandDepth, NodeIndent, PathSeparator, FindNode()

    +
    • +
  • +

    Image Customization - CollapseImageUrl, ExpandImageUrl, NoExpandImageUrl, CollapseImageToolTip, ExpandImageToolTip, LineImagesFolder

    +
    • +
  • Data Binding Configuration - AutoGenerateDataBindings, MaxDataBindDepth, EnableClientScript
    • +
+

Accessibility Features

+

The TreeView component includes an optional UseAccessibilityFeatures parameter that enhances the component for users with disabilities, particularly for keyboard navigation and screen reader support.

+

Enabling Accessibility Features

+

To enable accessibility features, set the UseAccessibilityFeatures parameter to true:

+
<TreeView UseAccessibilityFeatures="true">
+    <Nodes>
+        <TreeNode Text="Root Node" Expanded="true">
+            <TreeNode Text="Child Node" />
+        </TreeNode>
+    </Nodes>
+</TreeView>
+
+

When Accessibility Features are Enabled

+

The TreeView component provides the following enhancements:

+

ARIA Attributes

+
    +
  • role="tree": Applied to the TreeView container to identify it as a tree widget
    • +
  • aria-label="Tree navigation": Provides a descriptive label for screen readers
    • +
  • role="treeitem": Applied to each TreeNode to identify it as a tree item
    • +
  • aria-level: Indicates the depth level of each node (1 for root nodes, 2 for children, etc.)
    • +
  • aria-expanded: For nodes with children, indicates whether the node is expanded ("true") or collapsed ("false")
    • +
  • aria-label: Added to expand/collapse links to provide descriptive text for screen readers
    • +
+

Keyboard Navigation

+

With accessibility features enabled, users can navigate the TreeView using keyboard shortcuts:

+
    +
  • Arrow Right (→): Expands a collapsed node that has children
    • +
  • Arrow Left (←): Collapses an expanded node that has children
    • +
  • Enter or Space: Activates the node's link or expands/collapses the node
    • +
  • Tab: Moves focus into and out of the TreeView
    • +
+

Focus Management

+
    +
  • Each TreeNode receives a tabindex="0" attribute, making it keyboard accessible
    • +
  • Nodes can receive focus and respond to keyboard events
    • +
  • Visual focus indicators follow browser defaults
    • +
+

Benefits for Different Users

+

The accessibility features address several user needs:

+
    +
  1. Keyboard Users: Can navigate and interact with the TreeView without a mouse
    2. +
  2. Screen Reader Users: Get proper semantic information about the tree structure and node states
    3. +
  3. Speech Recognition Users: Benefit from larger interactive areas due to keyboard focus support
    4. +
  4. Touch Device Users: While the core issue of small touch targets isn't fully addressed, keyboard equivalents provide an alternative interaction method
    5. +
+

Backwards Compatibility

+

By default, UseAccessibilityFeatures is false, ensuring existing implementations continue to work without changes. The HTML output remains identical to the original Web Forms TreeView when accessibility features are disabled.

+

Usage Notes

+
    +
  • ShowCheckBoxes attribute, when specifying multiple values, should be separated by a vertical pipe | instead of commas
    • +
  • For the best user experience with assistive technologies, set UseAccessibilityFeatures="true"
    • +
+

Syntax Comparison

+
+
+
+
<asp:TreeView
+    AccessKey="string"
+    AutoGenerateDataBindings="True|False"
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
+        Inset|Outset"
+    BorderWidth="size"
+    CollapseImageToolTip="string"
+    CollapseImageUrl="uri"
+    CssClass="string"
+    DataSource="string"
+    DataSourceID="string"
+    EnableClientScript="True|False"
+    Enabled="True|False"
+    EnableTheming="True|False"
+    EnableViewState="True|False"
+    ExpandDepth="string|FullyExpand|0|1|2|3|4|5|6|7|8|9|10|11|12|13|
+        14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30"
+    ExpandImageToolTip="string"
+    ExpandImageUrl="uri"
+    Font-Bold="True|False"
+    Font-Italic="True|False"
+    Font-Names="string"
+    Font-Overline="True|False"
+    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
+       Large|X-Large|XX-Large"
+    Font-Strikeout="True|False"
+    Font-Underline="True|False"
+    ForeColor="color name|#dddddd"
+    Height="size"
+    ID="string"
+    ImageSet="Custom|XPFileExplorer|Msdn|WindowsHelp|Simple|Simple2|
+        BulletedList|BulletedList2|BulletedList3|BulletedList4|
+        Arrows|News|Contacts|Inbox|Events|Faq"
+    LineImagesFolder="string"
+    MaxDataBindDepth="integer"
+    NodeIndent="integer"
+    NodeWrap="True|False"
+    NoExpandImageUrl="uri"
+    OnDataBinding="DataBinding event handler"
+    OnDataBound="DataBound event handler"
+    OnDisposed="Disposed event handler"
+    OnInit="Init event handler"
+    OnLoad="Load event handler"
+    OnPreRender="PreRender event handler"
+    OnSelectedNodeChanged="SelectedNodeChanged event handler"
+    OnTreeNodeCheckChanged="TreeNodeCheckChanged event handler"
+    OnTreeNodeCollapsed="TreeNodeCollapsed event handler"
+    OnTreeNodeDataBound="TreeNodeDataBound event handler"
+    OnTreeNodeExpanded="TreeNodeExpanded event handler"
+    OnTreeNodePopulate="TreeNodePopulate event handler"
+    OnUnload="Unload event handler"
+    PathSeparator="string"
+    PopulateNodesFromClient="True|False"
+    runat="server"
+    ShowCheckBoxes="None|Root|Parent|Leaf|All"
+    ShowExpandCollapse="True|False"
+    ShowLines="True|False"
+    SkinID="string"
+    SkipLinkText="string"
+    Style="string"
+    TabIndex="integer"
+    Target="string"
+    ToolTip="string"
+    Visible="True|False"
+    Width="size"
+>
+        <DataBindings>
+                <asp:TreeNodeBinding
+                    DataMember="string"
+                    Depth="integer"
+                    FormatString="string"
+                    ImageToolTip="string"
+                    ImageToolTipField="string"
+                    ImageUrl="uri"
+                    ImageUrlField="string"
+                    NavigateUrl="uri"
+                    NavigateUrlField="string"
+                    PopulateOnDemand="True|False"
+                    SelectAction="Select|Expand|SelectExpand|None"
+                    ShowCheckBox="string"
+                    Target="string"
+                    TargetField="string"
+                    Text="string"
+                    TextField="string"
+                    ToolTip="string"
+                    ToolTipField="string"
+                    Value="string"
+                    ValueField="string"
+                />
+        </DataBindings>
+        <HoverNodeStyle />
+        <LeafNodeStyle
+            BackColor="color name|#dddddd"
+            BorderColor="color name|#dddddd"
+            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
+                Groove|Ridge|Inset|Outset"
+            BorderWidth="size"
+            ChildNodesPadding="size"
+            CssClass="string"
+            Font-Bold="True|False"
+            Font-Italic="True|False"
+            Font-Names="string"
+            Font-Overline="True|False"
+            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
+                Medium|Large|X-Large|XX-Large"
+            Font-Strikeout="True|False"
+            Font-Underline="True|False"
+            ForeColor="color name|#dddddd"
+            Height="size"
+            HorizontalPadding="size"
+            ImageUrl="uri"
+            NodeSpacing="size"
+            OnDisposed="Disposed event handler"
+            VerticalPadding="size"
+            Width="size"
+        />
+        <LevelStyles>
+                <asp:TreeNodeStyle
+                    BackColor="color name|#dddddd"
+                    BorderColor="color name|#dddddd"
+                    BorderStyle="NotSet|None|Dotted|Dashed|Solid|
+                        Double|Groove|Ridge|Inset|Outset"
+                    BorderWidth="size"
+                    ChildNodesPadding="size"
+                    CssClass="string"
+                    Font-Bold="True|False"
+                    Font-Italic="True|False"
+                    Font-Names="string"
+                    Font-Overline="True|False"
+                    Font-Size="string|Smaller|Larger|XX-Small|
+                        X-Small|Small|Medium|Large|X-Large|XX-Large"
+                    Font-Strikeout="True|False"
+                    Font-Underline="True|False"
+                    ForeColor="color name|#dddddd"
+                    Height="size"
+                    HorizontalPadding="size"
+                    ImageUrl="uri"
+                    NodeSpacing="size"
+                    OnDisposed="Disposed event handler"
+                    VerticalPadding="size"
+                    Width="size"
+                />
+        </LevelStyles>
+        <Nodes>
+                <asp:TreeNode
+                    Checked="True|False"
+                    Expanded="string"
+                    ImageToolTip="string"
+                    ImageUrl="uri"
+                    NavigateUrl="uri"
+                    PopulateOnDemand="True|False"
+                    SelectAction="Select|Expand|SelectExpand|None"
+                    Selected="True|False"
+                    ShowCheckBox="string"
+                    Target="string"
+                    Text="string"
+                    ToolTip="string"
+                    Value="string"
+>
+                </asp:TreeNode>
+        </Nodes>
+        <NodeStyle
+            BackColor="color name|#dddddd"
+            BorderColor="color name|#dddddd"
+            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
+                Groove|Ridge|Inset|Outset"
+            BorderWidth="size"
+            ChildNodesPadding="size"
+            CssClass="string"
+            Font-Bold="True|False"
+            Font-Italic="True|False"
+            Font-Names="string"
+            Font-Overline="True|False"
+            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
+                Medium|Large|X-Large|XX-Large"
+            Font-Strikeout="True|False"
+            Font-Underline="True|False"
+            ForeColor="color name|#dddddd"
+            Height="size"
+            HorizontalPadding="size"
+            ImageUrl="uri"
+            NodeSpacing="size"
+            OnDisposed="Disposed event handler"
+            VerticalPadding="size"
+            Width="size"
+        />
+        <ParentNodeStyle
+            BackColor="color name|#dddddd"
+            BorderColor="color name|#dddddd"
+            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
+                Groove|Ridge|Inset|Outset"
+            BorderWidth="size"
+            ChildNodesPadding="size"
+            CssClass="string"
+            Font-Bold="True|False"
+            Font-Italic="True|False"
+            Font-Names="string"
+            Font-Overline="True|False"
+            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
+                Medium|Large|X-Large|XX-Large"
+            Font-Strikeout="True|False"
+            Font-Underline="True|False"
+            ForeColor="color name|#dddddd"
+            Height="size"
+            HorizontalPadding="size"
+            ImageUrl="uri"
+            NodeSpacing="size"
+            OnDisposed="Disposed event handler"
+            VerticalPadding="size"
+            Width="size"
+        />
+        <RootNodeStyle
+            BackColor="color name|#dddddd"
+            BorderColor="color name|#dddddd"
+            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
+                Groove|Ridge|Inset|Outset"
+            BorderWidth="size"
+            ChildNodesPadding="size"
+            CssClass="string"
+            Font-Bold="True|False"
+            Font-Italic="True|False"
+            Font-Names="string"
+            Font-Overline="True|False"
+            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
+                Medium|Large|X-Large|XX-Large"
+            Font-Strikeout="True|False"
+            Font-Underline="True|False"
+            ForeColor="color name|#dddddd"
+            Height="size"
+            HorizontalPadding="size"
+            ImageUrl="uri"
+            NodeSpacing="size"
+            OnDisposed="Disposed event handler"
+            VerticalPadding="size"
+            Width="size"
+        />
+        <SelectedNodeStyle
+            BackColor="color name|#dddddd"
+            BorderColor="color name|#dddddd"
+            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
+                Groove|Ridge|Inset|Outset"
+            BorderWidth="size"
+            ChildNodesPadding="size"
+            CssClass="string"
+            Font-Bold="True|False"
+            Font-Italic="True|False"
+            Font-Names="string"
+            Font-Overline="True|False"
+            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
+                Medium|Large|X-Large|XX-Large"
+            Font-Strikeout="True|False"
+            Font-Underline="True|False"
+            ForeColor="color name|#dddddd"
+            Height="size"
+            HorizontalPadding="size"
+            ImageUrl="uri"
+            NodeSpacing="size"
+            OnDisposed="Disposed event handler"
+            VerticalPadding="size"
+            Width="size"
+        />
+</asp:TreeView>
+
+
+
+
<TreeView
+    AutoGenerateDataBindings=bool
+    CollapseImageToolTip=string
+    CollapseImageUrl=string
+    CssClass=string
+    DataSource=XmlDocument
+    EnableClientScript=bool
+    ExpandDepth=int
+    ExpandImageToolTip=string
+    ExpandImageUrl=string
+    ID=string
+    LineImagesFolder=string
+    MaxDataBindDepth=int
+    NodeIndent=int
+    NoExpandImageUrl=string
+    PathSeparator=char
+    SelectedNodeChanged=EventCallback<TreeNodeEventArgs>
+    ShowCheckBoxes="None|Root|Parent|Leaf|All"
+    ShowExpandCollapse=bool
+    ShowLines=bool
+    Target=string
+    UseAccessibilityFeatures=bool
+    Visible=bool
+>
+    <HoverNodeStyle CssClass="string" ... />
+    <LeafNodeStyle CssClass="string" ... />
+    <NodeStyle CssClass="string" ... />
+    <Nodes>
+        <TreeNode
+            Checked=bool
+            Expanded=bool
+            ImageUrl=string
+            NavigateUrl=string
+            Selected=bool
+            ShowCheckBox=bool
+            Target=string
+            Text=string
+            ToolTip=string
+            Value=string
+        >
+            <TreeNode Text="Child" Value="child" />
+        </TreeNode>
+    </Nodes>
+    <ParentNodeStyle CssClass="string" ... />
+    <RootNodeStyle CssClass="string" ... />
+    <SelectedNodeStyle CssClass="string" ... />
+</TreeView>
+
+
+
+
+

Examples

+

Basic TreeView with Nodes

+
<TreeView ShowExpandCollapse="true">
+    <Nodes>
+        <TreeNode Text="Products" Value="products" Expanded="true">
+            <TreeNode Text="Electronics" Value="electronics">
+                <TreeNode Text="Laptops" Value="laptops" />
+                <TreeNode Text="Phones" Value="phones" />
+            </TreeNode>
+            <TreeNode Text="Clothing" Value="clothing">
+                <TreeNode Text="Shirts" Value="shirts" />
+                <TreeNode Text="Pants" Value="pants" />
+            </TreeNode>
+        </TreeNode>
+    </Nodes>
+</TreeView>
+
+

Node Selection

+
<TreeView SelectedNodeChanged="HandleNodeSelected">
+    <Nodes>
+        <TreeNode Text="Home" Value="home" />
+        <TreeNode Text="About" Value="about" />
+        <TreeNode Text="Contact" Value="contact" />
+    </Nodes>
+    <SelectedNodeStyle CssClass="selected" BackColor="LightBlue" />
+</TreeView>
+
+<p>Selected: @selectedValue</p>
+
+@code {
+    private string selectedValue = "";
+
+    private void HandleNodeSelected(TreeNodeEventArgs e)
+    {
+        selectedValue = e.Node.Value;
+    }
+}
+
+

Node-Level Styles

+
@* Apply different styles to root, parent, and leaf nodes *@
+<TreeView ShowExpandCollapse="true">
+    <Nodes>
+        <TreeNode Text="Documents" Value="docs" Expanded="true">
+            <TreeNode Text="Reports" Value="reports">
+                <TreeNode Text="Q1 Report" Value="q1" />
+                <TreeNode Text="Q2 Report" Value="q2" />
+            </TreeNode>
+        </TreeNode>
+    </Nodes>
+    <RootNodeStyle CssClass="root-node" ForeColor="DarkBlue" Font-Bold="true" />
+    <ParentNodeStyle CssClass="parent-node" ForeColor="Navy" />
+    <LeafNodeStyle CssClass="leaf-node" ForeColor="Black" />
+    <HoverNodeStyle CssClass="hover-node" BackColor="LightYellow" />
+    <SelectedNodeStyle CssClass="selected-node" BackColor="LightBlue" />
+</TreeView>
+
+
+

Style Priority

+

When multiple styles apply to a node, the priority order is: +SelectedNodeStyle > type-specific style (Root/Parent/Leaf) > NodeStyle (fallback).

+
+

Expand/Collapse Control

+
@* ExpandDepth controls initial expansion. -1 = fully expanded. *@
+<TreeView @ref="treeRef"
+          ExpandDepth="1"
+          NodeIndent="25"
+          PathSeparator="/">
+    <Nodes>
+        <TreeNode Text="Root" Value="root">
+            <TreeNode Text="Level 1" Value="level1">
+                <TreeNode Text="Level 2" Value="level2" />
+            </TreeNode>
+        </TreeNode>
+    </Nodes>
+</TreeView>
+
+<Button Text="Expand All" OnClick="ExpandAll" />
+<Button Text="Collapse All" OnClick="CollapseAll" />
+<Button Text="Find Node" OnClick="FindSpecific" />
+
+@code {
+    private TreeView treeRef;
+
+    private void ExpandAll() => treeRef.ExpandAll();
+    private void CollapseAll() => treeRef.CollapseAll();
+    private void FindSpecific()
+    {
+        // Find node by path: "root/level1/level2"
+        var node = treeRef.FindNode("root/level1/level2");
+    }
+}
+
+

Data Binding with XmlDocument

+
@using System.Xml
+
+<TreeView DataSource="@sitemapXml"
+          ShowExpandCollapse="true">
+    <DataBindings>
+        <TreeNodeBinding DataMember="siteMapNode"
+                         TextField="title"
+                         NavigateUrlField="url" />
+    </DataBindings>
+</TreeView>
+
+@code {
+    private XmlDocument sitemapXml;
+
+    protected override void OnInitialized()
+    {
+        sitemapXml = new XmlDocument();
+        sitemapXml.LoadXml(@"
+            <siteMap>
+                <siteMapNode title='Home' url='/'>
+                    <siteMapNode title='Products' url='/products' />
+                    <siteMapNode title='About' url='/about' />
+                </siteMapNode>
+            </siteMap>");
+    }
+}
+
+

Selection Properties Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property/EventTypeDefaultDescription
SelectedNodeTreeNodenullRead-only. The currently selected node.
SelectedValuestringnullRead-only. The Value of the selected node.
SelectedNodeChangedEventCallback<TreeNodeEventArgs>—Fires when the selected node changes.
+

Node Style Sub-Components Reference

+

All node style sub-components use TreeNodeStyle which supports:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
CssClassstringCSS class name
BackColorWebColorBackground color
ForeColorWebColorText color
FontFontInfoFont settings
ImageUrlstringCustom node icon URL
HorizontalPaddingUnitHorizontal padding
VerticalPaddingUnitVertical padding
ChildNodesPaddingUnitPadding around child nodes
NodeSpacingUnitSpacing between nodes
+

Available style sub-components:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentApplied To
<NodeStyle>All nodes (fallback)
<HoverNodeStyle>Nodes on mouse hover
<RootNodeStyle>Top-level nodes (no parent)
<ParentNodeStyle>Nodes that have children
<LeafNodeStyle>Nodes with no children
<SelectedNodeStyle>The currently selected node
+

Expand/Collapse Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property/MethodTypeDefaultDescription
ExpandDepthint-1Initial expansion depth. -1 = fully expanded, 0 = all collapsed.
NodeIndentint20Pixel indent per nesting level.
PathSeparatorchar'/'Separator character for FindNode() value paths.
ExpandAll()void—Expands all nodes recursively.
CollapseAll()void—Collapses all nodes recursively.
FindNode(string)TreeNode—Finds a node by its PathSeparator-delimited value path (e.g., "root/child/leaf").
+

Image Customization Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
CollapseImageUrlstringnullURL of the image displayed on collapsible (expanded) nodes.
CollapseImageToolTipstringnullTooltip text for the collapse image.
ExpandImageUrlstringnullURL of the image displayed on expandable (collapsed) nodes.
ExpandImageToolTipstringnullTooltip text for the expand image.
NoExpandImageUrlstringnullURL of the image displayed on leaf nodes (no children).
LineImagesFolderstringnullPath to the folder containing line images for tree structure.
+

Data Binding Configuration Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
AutoGenerateDataBindingsboolfalseWhether to automatically create data bindings from a data source.
MaxDataBindDepthint-1Maximum hierarchy depth for data binding. -1 binds all levels.
EnableClientScriptbooltrueMigration stub — accepted for Web Forms compatibility. Blazor does not use client scripts.
+

See Also

+
    +
  • Menu — Hierarchical navigation menu
    • +
  • SiteMapPath — Breadcrumb navigation path
    • +
  • HyperLink — Simple link navigation
    • +
  • ImageMap — Image with clickable regions
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/Databinder/index.html b/site/UtilityFeatures/Databinder/index.html new file mode 100644 index 000000000..894a4f75a --- /dev/null +++ b/site/UtilityFeatures/Databinder/index.html @@ -0,0 +1,4659 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Databinder - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Databinder

+ +

In Web Forms applications, there is a somewhat standard approach of formatting and placing data in controls by using the DataBinder object. The DataBinder would be used in ItemTemplate, AlternatingItemTemplate, and other control templates to indicate where data would be formatted and placed. Microsoft's original documentation about the DataBinder are available.

+

ASP.NET Syntax, Support and Migration

+

There are several common techniques that the DataBinder was used and various levels of support are provided:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web Forms SyntaxDescriptionBlazor Support
DataBinder.Eval(Container.DataItem, "PropertyName")Output the PropertyName of the current itemFully Supported for Container.DataItem
Eval("PropertyName")Output the PropertyName of the current itemFully Supported when using static
DataBinder.Eval(Container.DataItem, "PropertyName", "FormatString")Output the formatted value of PropertyName of the current item with the FormatStringFully Supported for Container.DataItem
Eval("PropertyName", "FormatString")Output the formatted value of PropertyName of the current item with the FormatStringFully Supported when using static
DataBinder.GetDataItemOutput the item currently operated onNot supported: Replace with calls to @context
DataBinder.GetPropertyValue(Container.DataItem, "PropertyName")Get the property requested as an object for further handlingOnly supported when passing in @context for the first argument. Recommendation: replace with @context.PropertyName to directly access the property in a strongly-typed manner
+

Support and Migration

+

The DataBinder is not recommended by Microsoft in Web Forms for use in high-performance applications due to the amount of reflection used to output and format content. Similarly, we do not recommend long-term use of the DataBinder and have marked it with an Obsolete flag indicating that there are methods to easily migrate syntax to be more Razor-performance-friendly.

+

Usage

+

To migrate your Web Forms control that is referencing the DataBinder to Blazor, start with syntax similar to the following:

+
<ItemTemplate>
+  <li><%#: DataBinder.Eval(Container.DataItem, "Price", "{0:C}") %></li>
+</ItemTemplate>
+
+

All of the databound components in this library support DataBinder syntax and can easily be converted by replacing the angle brackets with razor notation like the following:

+
<ItemTemplate>
+  <li>@DataBinder.Eval(Container.DataItem, "Price", "{0:C}")</li>
+</ItemTemplate>
+
+

That's a VERY simple conversion and its clear how we can continue to deliver the same feature and formatting using Blazor. You can even shorten the syntax to use the simple Eval keyword and get the same effect. Just include a @using static keyword near the top of your Blazor page with this syntax and you can using the shortened format of Eval.

+
@using static BlazorWebFormsComponents.DataBinder
+...
+<ItemTemplate>
+  <li>@Eval("Price", "{0:C}")</li>
+</ItemTemplate>
+
+

Note: Your Blazor application will emit compiler warnings while you continue to use the DataBinder.

+

Moving On

+

Moving on from the DataBinder to a more performant and simple Razor syntax is quite easy using an ItemContext and referencing the iterated item directly. This approach has the additional benefit of providing type-safety and compiler checking on the content of your Blazor pages.

+

Our Eval("Price") statement above is further simplified into:

+
<Repeater Context="Item">
+...
+    <ItemTemplate>
+      <li>@Item.Price.ToString("C")</li>
+    </ItemTemplate>
+...
+</Repeater>
+
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/EnumParameter/index.html b/site/UtilityFeatures/EnumParameter/index.html new file mode 100644 index 000000000..57a15e246 --- /dev/null +++ b/site/UtilityFeatures/EnumParameter/index.html @@ -0,0 +1,4837 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + EnumParameter - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

EnumParameter\<T>

+

EnumParameter<T> is a transparent wrapper struct that allows Blazor component parameters to accept both enum values and plain strings. This eliminates the most common migration friction point: the Razor compiler requiring @() expression syntax for enum values.

+

Original Web Forms controls accepted string attribute values and parsed them at runtime. Blazor's strongly-typed parameter binding normally requires explicit enum syntax. EnumParameter<T> bridges this gap.

+

Background

+

In ASP.NET Web Forms, you could write:

+
<asp:GridView GridLines="None" runat="server" />
+<asp:Panel ScrollBars="Vertical" runat="server" />
+
+

Web Forms parsed the string "None" into the GridLines enum at runtime. In Blazor, enum parameters normally require Razor expression syntax:

+
@* Without EnumParameter — requires wrapping in @() *@
+<GridView GridLines="@(GridLines.None)" />
+<Panel ScrollBars="@(ScrollBars.Vertical)" />
+
+

This means every migrated page needs manual touch-up of enum attributes, which is error-prone at scale.

+

How It Works

+

With EnumParameter<T>, both syntaxes work:

+
@* String value — just like Web Forms *@
+<GridView GridLines="None" />
+<Panel ScrollBars="Vertical" />
+
+@* Enum value — standard Blazor syntax still works *@
+<GridView GridLines="@(GridLines.None)" />
+
+

The wrapper provides implicit conversions in both directions:

+
    +
  • string → EnumParameter<T>: Parses the string (case-insensitive) into the enum value
    • +
  • T → EnumParameter<T>: Wraps the enum value directly
    • +
  • EnumParameter<T> → T: Unwraps back to the original enum transparently
    • +
+

Supported Components

+

EnumParameter<T> is used across 46 components in the library, covering all enum parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentParameters
GridViewGridLines, SortDirection, HorizontalAlign
DetailsViewGridLines, HorizontalAlign
PanelScrollBars, HorizontalAlign, Direction
TextBoxTextMode
CalendarDayNameFormat, FirstDayOfWeek, NextPrevFormat, TitleFormat
BulletedListBulletStyle, DisplayMode
UpdatePanelUpdateMode, RenderMode
ScriptManagerScriptMode
LoginOrientation
LocalizeMode
...and many more
+

Usage Notes

+

In Migrated Markup

+

No changes needed — string enum values from Web Forms work as-is:

+
<GridView DataSource="@products"
+          GridLines="Both"
+          HorizontalAlign="Center"
+          AutoGenerateColumns="true" />
+
+

In Code-Behind

+

When comparing EnumParameter<T> values in C# code, the implicit conversion handles most cases:

+
@code {
+    // Direct comparison works via implicit conversion
+    private EnumParameter<GridLines> _gridLines = GridLines.None;
+
+    private void CheckGridLines()
+    {
+        if (_gridLines == GridLines.None) { /* works */ }
+    }
+}
+
+
+

Switch Statements

+

C# pattern matching does not use implicit conversions. In switch statements, use .Value:

+
switch (gridLines.Value)  // Not: switch (gridLines)
+{
+    case GridLines.None: break;
+    case GridLines.Both: break;
+}
+
+
+
+

Shouldly / Test Assertions

+

Some assertion libraries don't resolve extension methods for generic structs. Use .Value in test assertions:

+
cut.Instance.GridLines.Value.ShouldBe(GridLines.None);  // ✓
+// cut.Instance.GridLines.ShouldBe(GridLines.None);      // ✗ won't compile
+
+
+

Invalid Values

+

If an invalid string is passed, EnumParameter<T> throws an ArgumentException at parameter binding time:

+
@* This will throw ArgumentException — "Invalid" is not a GridLines value *@
+<GridView GridLines="Invalid" />
+
+

Moving On

+

EnumParameter<T> is a migration convenience. As you modernize your Blazor application:

+
    +
  1. Keep string syntax if it improves readability — there's no performance penalty
    2. +
  2. Switch to enum syntax (@(GridLines.None)) when you want compile-time safety and IDE IntelliSense
    3. +
  3. The wrapper has zero runtime overhead for enum-value assignments; string parsing only occurs for string-value assignments
    4. +
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/IDRendering/index.html b/site/UtilityFeatures/IDRendering/index.html new file mode 100644 index 000000000..edfa69c2d --- /dev/null +++ b/site/UtilityFeatures/IDRendering/index.html @@ -0,0 +1,5262 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ID Rendering - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ID Rendering and JavaScript Integration

+

One of the key features when migrating from ASP.NET Web Forms to Blazor is maintaining compatibility with existing JavaScript code that relies on HTML element IDs. In Web Forms, controls automatically rendered with predictable IDs (via the ClientID property), allowing JavaScript to target specific elements on the page.

+

The BlazorWebFormsComponents library provides full support for ID rendering, enabling seamless JavaScript integration for migrated applications.

+

Overview

+

In Web Forms, every control had an ID property that determined how it would be rendered in HTML. The framework would generate a ClientID that included the full naming container hierarchy, ensuring unique IDs across the page.

+

For example: +

<asp:Panel ID="userPanel" runat="server">
+    <asp:TextBox ID="txtName" runat="server" />
+</asp:Panel>
+

+

Would render as: +

<div id="userPanel">
+    <input id="userPanel_txtName" type="text" />
+</div>
+

+

Implementation in Blazor

+

BlazorWebFormsComponents provides the same functionality with minimal changes:

+

Basic ID Rendering

+

Set the ID parameter on any component:

+
<Label ID="lblName" Text="Your Name:" />
+<TextBox ID="txtName" Placeholder="Enter name" />
+<Button ID="btnSubmit" Text="Submit" />
+
+

Renders as: +

<span id="lblName">Your Name:</span>
+<input id="txtName" type="text" placeholder="Enter name" />
+<button id="btnSubmit">Submit</button>
+

+

Hierarchical IDs

+

Nested components automatically generate hierarchical IDs following the Web Forms pattern:

+
<Panel ID="userPanel">
+    <Label ID="lblEmail" Text="Email:" />
+    <TextBox ID="txtEmail" />
+</Panel>
+
+

Renders as: +

<div id="userPanel">
+    <span id="userPanel_lblEmail">Email:</span>
+    <input id="userPanel_txtEmail" type="text" />
+</div>
+

+

ClientID Property

+

Components expose a ClientID property (just like Web Forms) that returns the fully-qualified ID including parent hierarchy:

+
@code {
+    private TextBox myTextBox;
+
+    protected override void OnAfterRender(bool firstRender)
+    {
+        if (firstRender)
+        {
+            // Access the generated ID
+            var id = myTextBox.ClientID; // Returns "userPanel_txtEmail" if nested
+        }
+    }
+}
+
+

JavaScript Integration

+

Accessing Elements by ID

+

Your existing JavaScript code continues to work without modification:

+
// Standard DOM API
+var textBox = document.getElementById('txtName');
+var value = textBox.value;
+
+// Hierarchical IDs
+var email = document.getElementById('userPanel_txtEmail');
+
+// jQuery
+var name = $('#txtName').val();
+var email = $('#userPanel_txtEmail').val();
+
+

Event Handlers

+

Attach JavaScript event handlers to components with IDs:

+
document.addEventListener('DOMContentLoaded', function() {
+    var submitBtn = document.getElementById('btnSubmit');
+    submitBtn.addEventListener('click', function(e) {
+        console.log('Submit clicked!');
+    });
+});
+
+

Supported Components

+

ID rendering is supported on all major components:

+

Editor Controls

+
    +
  • Button
    • +
  • CheckBox
    • +
  • HiddenField
    • +
  • HyperLink
    • +
  • Image
    • +
  • ImageButton
    • +
  • Label
    • +
  • LinkButton
    • +
  • Panel
    • +
  • RadioButton
    • +
  • TextBox
    • +
+

Data Controls

+
    +
  • TreeView (container)
    • +
  • GridView (when implemented with IDs)
    • +
  • DataList (when implemented with IDs)
    • +
+

Other Controls

+

All components inheriting from BaseWebFormsComponent support the ID parameter.

+

Important Notes

+

Opt-in Behavior

+
    +
  • ID rendering only occurs when the ID parameter is explicitly set
    • +
  • Components without an ID parameter work exactly as before (no id attribute in HTML)
    • +
  • This maintains backward compatibility with existing applications
    • +
+

Naming Containers

+
    +
  • Parent components with IDs become naming containers
    • +
  • Child component IDs are prefixed with the parent's ID
    • +
  • Format: ParentID_ChildID (using underscore separator)
    • +
  • Follows the ASP.NET Web Forms ClientIDMode.AutoID pattern
    • +
  • For explicit naming scope control, see NamingContainer and WebFormsPage
    • +
+

Differences from Web Forms

+
    +
  1. +

    No ClientIDMode: The library uses a simplified approach similar to ClientIDMode.Static when no parent has an ID, and ClientIDMode.AutoID when parents have IDs.

    +
    2. +
  2. +

    No UniqueID: Web Forms had both ClientID and UniqueID. Blazor only needs ClientID since it doesn't use postback naming schemes.

    +
    3. +
  3. +

    Optional IDs: Unlike Web Forms which often auto-generated IDs (like ctl00), BlazorWebFormsComponents only renders IDs when explicitly set.

    +
    4. +
+

Migration Tips

+

Finding JavaScript Dependencies

+

When migrating a Web Forms application:

+
    +
  1. Search your JavaScript files for document.getElementById() or $('#...)
    2. +
  2. Identify which controls need IDs to maintain JavaScript functionality
    3. +
  3. Add the ID parameter to those components in your Blazor markup
    4. +
+

Example Migration

+

Before (Web Forms): +

<asp:Panel ID="loginPanel" runat="server">
+    <asp:TextBox ID="txtUsername" runat="server" />
+    <asp:Button ID="btnLogin" runat="server" OnClick="Login_Click" />
+</asp:Panel>
+
+<script>
+    $(document).ready(function() {
+        $('#btnLogin').click(function() {
+            var username = $('#loginPanel_txtUsername').val();
+            if (!username) {
+                alert('Please enter username');
+                return false;
+            }
+        });
+    });
+</script>
+

+

After (Blazor): +

<Panel ID="loginPanel">
+    <TextBox ID="txtUsername" />
+    <Button ID="btnLogin" OnClick="Login_Click" />
+</Panel>
+
+<script>
+    $(document).ready(function() {
+        $('#btnLogin').click(function() {
+            var username = $('#loginPanel_txtUsername').val();
+            if (!username) {
+                alert('Please enter username');
+                return false;
+            }
+        });
+    });
+</script>
+

+

The JavaScript requires no changes - it continues to work exactly as before.

+

ComponentIdGenerator

+

For advanced scenarios, the library provides a ComponentIdGenerator utility class:

+
// Get the full client ID including parent hierarchy
+var clientId = ComponentIdGenerator.GetClientID(component);
+
+// Generate a child element ID
+var childId = ComponentIdGenerator.GetChildClientID(component, "childSuffix");
+
+// Generate an ID for data-bound items
+var itemId = ComponentIdGenerator.GetItemClientID(component, itemIndex);
+
+

This is useful when creating custom components that need to generate IDs for child elements.

+

Best Practices

+
    +
  1. Use IDs Selectively: Only add IDs to components that need JavaScript interaction
    2. +
  2. Keep Names Descriptive: Use meaningful ID names (e.g., txtEmail not txt1)
    3. +
  3. Follow Conventions: Use Web Forms naming conventions for easier migration
    4. +
  4. Plan for Hierarchy: Consider the parent-child relationship when naming components
    5. +
  5. Test JavaScript: Verify all JavaScript interactions work after adding IDs
    6. +
+

Examples

+

See the ID Rendering Sample for a complete working example demonstrating: +- Basic ID rendering +- Hierarchical ID generation +- JavaScript integration +- Multiple control types

+ +
    +
  • NamingContainer - Explicit naming scope component for ID hierarchy control
    • +
  • WebFormsPage - Combined naming container and theme wrapper
    • +
  • ViewState - Understanding state management in migrated applications
    • +
  • JavaScript Setup - Configuring JavaScript for Blazor
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/JavaScriptSetup/index.html b/site/UtilityFeatures/JavaScriptSetup/index.html new file mode 100644 index 000000000..ba3879cef --- /dev/null +++ b/site/UtilityFeatures/JavaScriptSetup/index.html @@ -0,0 +1,4851 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + JavaScript Setup - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

JavaScript Setup

+

BlazorWebFormsComponents requires a small JavaScript file to handle certain Web Forms features like OnClientClick event handling and page title management. This document explains the different ways to include this JavaScript in your application.

+

Options for Including JavaScript

+

There are three ways to include the required JavaScript, listed from most recommended to least:

+ +

The easiest and most modern approach is to register the BlazorWebFormsComponents service in your Program.cs. This automatically handles JavaScript loading with no manual script tags required.

+
// Program.cs
+builder.Services.AddBlazorWebFormsComponents();
+
+

That's it! The JavaScript module is automatically imported on first component render using ES module dynamic imports.

+
+

Best for new projects

+

This approach is recommended for new projects or when you have control over the application's service configuration.

+
+

Option 2: Script Loader Component

+

Add the <BlazorWebFormsScripts /> component once in your layout or App.razor:

+
@* In App.razor or your layout *@
+<body>
+    <Routes @rendermode="InteractiveServer" />
+
+    <script src="_framework/blazor.web.js"></script>
+    <BlazorWebFormsScripts />
+</body>
+
+

This component automatically loads the JavaScript module when rendered.

+

Option 3: HeadContent Component

+

Use the <BlazorWebFormsHead /> component to inject the script tag into the page head:

+
@* In any component or layout *@
+<BlazorWebFormsHead />
+
+

This uses Blazor's <HeadContent> to add the script tag to the document head.

+

Option 4: Manual Script Tag (Legacy)

+

You can manually add the script tag to your layout. This is the traditional approach and still works:

+
<!-- In App.razor or _Host.cshtml -->
+<body>
+    <!-- Your content -->
+
+    <script src="_framework/blazor.web.js"></script>
+    <script src="_content/Fritz.BlazorWebFormsComponents/js/Basepage.js"></script>
+</body>
+
+
+

Placement matters

+

The script tag must be placed after the Blazor framework script (blazor.web.js or blazor.server.js).

+
+

What the JavaScript Does

+

The JavaScript file provides:

+
    +
  1. OnClientClick Support - Handles the OnClientClick attribute on buttons and other controls, allowing client-side JavaScript to run before server events
    2. +
  2. Page Title Management - Provides functions to get and set the page title programmatically
    3. +
  3. Post-Render Initialization - Sets up event handlers for Web Forms compatibility features after Blazor renders
    4. +
+

Choosing the Right Option

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ScenarioRecommended Option
New projectsOption 1: Service Registration
Existing projects with layout accessOption 2 or 3: Component-based
Projects with strict CSP policiesOption 1: Service Registration (uses ES modules)
Legacy projects or minimal changesOption 4: Manual Script Tag
+

Troubleshooting

+

Script Not Loading

+

If you see JavaScript errors related to bwfc.Page being undefined:

+
    +
  1. Verify the script is included using one of the methods above
    2. +
  2. Check browser developer tools Network tab to ensure the script is loaded
    3. +
  3. Ensure the script is placed after the Blazor framework script
    4. +
+

OnClientClick Not Working

+

The OnClientClick functionality requires the JavaScript to be loaded. If buttons with OnClientClick aren't executing client-side code:

+
    +
  1. Confirm JavaScript is loaded (check browser console)
    2. +
  2. Ensure the component has rendered at least once (the initialization runs on first render)
    3. +
+

Migration Note

+

When migrating from Web Forms, you don't need to change how OnClientClick works in your markup. The BlazorWebFormsComponents library handles the translation automatically:

+
@* This works the same as in Web Forms *@
+<Button Text="Submit" OnClientClick="return confirm('Are you sure?');" OnClick="HandleSubmit" />
+
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/L2AutomationShims/index.html b/site/UtilityFeatures/L2AutomationShims/index.html new file mode 100644 index 000000000..62596106e --- /dev/null +++ b/site/UtilityFeatures/L2AutomationShims/index.html @@ -0,0 +1,4952 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + L2 Automation Shims - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

L2 Automation Shims

+

BlazorWebFormsComponents includes a set of Layer 2 (L2) automation shims — library-level features that eliminate the most common manual fixes required after automated migration. These shims exist because Blazor's Razor compiler is stricter than Web Forms' parser: Web Forms silently coerced strings to enums, resolved virtual paths, and provided ambient page properties that Blazor does not.

+

By absorbing these differences into the BWFC library itself, migrated markup compiles with fewer manual interventions.

+

The Problem

+

Automated migration (Layer 1) converts Web Forms markup to Blazor syntax. But the converted code often needs Layer 2 manual fixes because:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web Forms BehaviorBlazor BehaviorResult
GridLines="None" — string parsed at runtimeEnum parameter requires @(GridLines.None)❌ Every enum attribute needs wrapping
Width="125px" — string parsed by UnitConverterUnit type required explicit cast❌ Every width/height needs Unit.Parse()
Response.Redirect("~/Products.aspx")No Response object exists❌ All redirects need rewriting
ViewState["key"] = valueNo ViewState dictionary❌ All ViewState access needs replacement
GetRouteUrl("Products", new { id })No GetRouteUrl method❌ Route URL generation needs rewriting
+

Each of these generates 5-20+ manual fixes per page across a typical application. The L2 shims eliminate them.

+

Shim Overview

+

1. EnumParameter\<T> — String-Accepting Enum Parameters

+

Problem: GridLines="None" won't compile because Blazor expects GridLines="@(GridLines.None)"

+

Solution: All 46 BWFC components with enum parameters now use EnumParameter<T>, which accepts both strings and enum values via implicit conversion.

+
@* Both work — no wrapping needed *@
+<GridView GridLines="None" />
+<GridView GridLines="@(GridLines.None)" />
+
+

📖 Full documentation →

+
+

2. Implicit Unit Conversion — String-Accepting Width/Height

+

Problem: Width="125px" won't compile because Unit required explicit construction

+

Solution: The Unit struct now has an implicit conversion from string, delegating to Unit.Parse().

+
@* String values work directly *@
+<Panel Width="200px" Height="100%" />
+<GridView Width="50em" />
+
+@* Numeric values still work *@
+<Panel Width="@(new Unit(200))" />
+
+

All CSS unit formats are supported: px, pt, %, em, ex, in, cm, mm.

+
+

3. Response.Redirect — Navigation Compatibility

+

Problem: Response.Redirect("~/Products.aspx") won't compile — there's no Response object in Blazor

+

Solution: WebFormsPageBase exposes a Response property returning a ResponseShim that wraps NavigationManager. The shim automatically strips ~/ prefixes and .aspx extensions.

+
@inherits WebFormsPageBase
+
+@code {
+    void GoToProducts() => Response.Redirect("~/Products.aspx");
+    // Navigates to /Products
+}
+
+

📖 Full documentation →

+
+

4. Page-Level ViewState — In-Memory Dictionary

+

Problem: ViewState["key"] = value won't compile on pages that don't have a ViewState property

+

Solution: WebFormsPageBase provides a Dictionary<string, object> property named ViewState. Values persist for the lifetime of the component instance (equivalent to private fields).

+
@inherits WebFormsPageBase
+
+@code {
+    protected override void OnInitialized()
+    {
+        #pragma warning disable CS0618 // Suppress obsolete warning
+        ViewState["ProductCount"] = 42;
+        var count = (int)ViewState["ProductCount"];
+        #pragma warning restore CS0618
+    }
+}
+
+
+

Marked Obsolete

+

ViewState is marked [Obsolete] to generate compiler warnings encouraging developers to refactor to typed properties. The warnings guide migration without breaking compilation.

+
+

📖 Existing documentation →

+
+

5. GetRouteUrl — Route URL Generation

+

Problem: GetRouteUrl("Products", new { id = 5 }) won't compile — no such method in Blazor components

+

Solution: WebFormsPageBase provides a GetRouteUrl() method that delegates to ASP.NET Core's LinkGenerator. It strips .aspx from route names for compatibility.

+
@inherits WebFormsPageBase
+
+@code {
+    private string GetProductUrl(int id)
+    {
+        return GetRouteUrl("ProductDetails", new { id });
+    }
+}
+
+

Using WebFormsPageBase

+

All page-level shims (Response, ViewState, GetRouteUrl, IsPostBack, Page.Title) are available through a single base class:

+
@inherits WebFormsPageBase
+@page "/products"
+
+<h1>@Page.Title</h1>
+
+<GridView DataSource="@_products" GridLines="None" Width="100%" />
+
+<Button Text="Dashboard" OnClick="GoToDashboard" />
+
+@code {
+    private List<Product> _products;
+
+    protected override void OnInitialized()
+    {
+        Page.Title = "Product Catalog";
+
+        if (!IsPostBack) // Always true in Blazor — guarded code always runs
+        {
+            _products = LoadProducts();
+        }
+    }
+
+    private void GoToDashboard()
+    {
+        Response.Redirect("~/Admin/Dashboard.aspx");
+    }
+}
+
+

Required Services

+

WebFormsPageBase requires several services to be registered. These are automatically configured when you call AddBlazorWebFormsComponents() in Program.cs:

+
builder.Services.AddBlazorWebFormsComponents();
+
+

This registers: +- IPageService (scoped) +- IHttpContextAccessor +- LinkGenerator (provided by ASP.NET Core routing)

+

Migration Impact

+

Based on migration testing with WingtipToys (19 pages) and ContosoUniversity (8 pages):

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ShimManual Fixes Eliminated Per PageTotal Across Typical App
EnumParameter\<T>3-8 enum wrappings60-150+ fixes
Unit implicit conversion2-5 width/height fixes40-100+ fixes
Response.Redirect1-3 redirect rewrites20-60+ fixes
ViewState dictionary0-5 ViewState accesses0-100+ fixes
GetRouteUrl0-2 route URL calls0-40+ fixes
Combined6-23 fixes per page120-450+ fixes eliminated
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/NamingContainer/index.html b/site/UtilityFeatures/NamingContainer/index.html new file mode 100644 index 000000000..9f352f77f --- /dev/null +++ b/site/UtilityFeatures/NamingContainer/index.html @@ -0,0 +1,5057 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + NamingContainer - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

NamingContainer

+

The NamingContainer component establishes a naming scope for child components, equivalent to INamingContainer in ASP.NET Web Forms. Child controls get IDs prefixed with this container's ID, separated by underscores — exactly as they did in Web Forms.

+

NamingContainer renders no HTML of its own. It is a purely structural component that exists solely to define the naming hierarchy for ID generation.

+

Why It Exists

+

In Web Forms, any control implementing INamingContainer created a scope so that child controls received fully-qualified ClientID values. This ensured unique IDs across the page and enabled JavaScript and CSS selectors that relied on predictable ID patterns like MainContent_txtUsername.

+

Blazor has no built-in equivalent. NamingContainer fills that gap, letting your migrated JavaScript and CSS continue to target elements by their original Web Forms IDs.

+

Features Supported in Blazor

+
    +
  • Naming scope — Prefixes child component IDs with the container's own ID using underscore separators
    • +
  • UseCtl00Prefix — Optionally prepends ctl00 to the naming hierarchy for full Web Forms ID compatibility
    • +
  • Nesting — Multiple NamingContainer components can be nested; IDs accumulate through the hierarchy
    • +
  • Visible — Controls whether child content renders (inherited from BaseWebFormsComponent)
    • +
+

Features NOT Supported

+
    +
  • ClientIDMode — Web Forms offered AutoID, Static, Predictable, and Inherit modes. This library uses a simplified model equivalent to AutoID.
    • +
  • UniqueID — The postback-oriented UniqueID (colon-separated) is not replicated; only ClientID (underscore-separated) is supported.
    • +
+

Web Forms Syntax

+
<%-- INamingContainer was typically an interface on custom controls or built-in containers --%>
+<asp:Panel ID="MainContent" runat="server">
+    <asp:TextBox ID="txtSearch" runat="server" />
+    <asp:Button ID="btnGo" runat="server" Text="Search" />
+</asp:Panel>
+
+

Rendered IDs: MainContent_txtSearch, MainContent_btnGo

+

With Page as the root naming container and ClientIDMode="AutoID":

+
<input id="ctl00_MainContent_txtSearch" type="text" />
+<input id="ctl00_MainContent_btnGo" type="submit" value="Search" />
+
+

Blazor Syntax

+
<NamingContainer ID="MainContent">
+    <TextBox ID="txtSearch" />
+    <Button ID="btnGo" Text="Search" />
+</NamingContainer>
+
+

With UseCtl00Prefix:

+
<NamingContainer ID="MainContent" UseCtl00Prefix="true">
+    <TextBox ID="txtSearch" />
+    <Button ID="btnGo" Text="Search" />
+</NamingContainer>
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDefaultDescription
IDstringnullSets the naming scope prefix for child component IDs
UseCtl00PrefixboolfalseWhen true, prepends ctl00 to the naming hierarchy
VisiblebooltrueControls whether child content renders
ChildContentRenderFragment—The child components to wrap
+

Examples

+

Basic Usage

+

Wrap a group of controls to establish a naming scope:

+
<NamingContainer ID="SearchPanel">
+    <Label ID="lblQuery" Text="Search:" />
+    <TextBox ID="txtQuery" />
+    <Button ID="btnSearch" Text="Go" />
+</NamingContainer>
+
+

Rendered IDs:

+ + + + + + + + + + + + + + + + + + + + + +
ComponentRendered id attribute
LabelSearchPanel_lblQuery
TextBoxSearchPanel_txtQuery
ButtonSearchPanel_btnSearch
+

Your existing JavaScript continues to work:

+
var query = document.getElementById('SearchPanel_txtQuery').value;
+
+

Nested Containers

+

NamingContainer components can be nested. Each level adds its ID as a prefix:

+
<NamingContainer ID="Page">
+    <NamingContainer ID="Sidebar">
+        <TextBox ID="txtFilter" />
+    </NamingContainer>
+    <NamingContainer ID="Content">
+        <Button ID="btnSave" Text="Save" />
+    </NamingContainer>
+</NamingContainer>
+
+

Rendered IDs:

+ + + + + + + + + + + + + + + + + +
ComponentRendered id attribute
TextBoxPage_Sidebar_txtFilter
ButtonPage_Content_btnSave
+

UseCtl00Prefix for Full Web Forms Compatibility

+

In Web Forms, the page-level naming container prepended ctl00 to all client IDs. Enable this behavior with UseCtl00Prefix:

+
<NamingContainer ID="MainContent" UseCtl00Prefix="true">
+    <TextBox ID="txtName" />
+    <Button ID="btnSubmit" Text="Submit" />
+</NamingContainer>
+
+

Rendered IDs:

+ + + + + + + + + + + + + + + + + +
ComponentRendered id attribute
TextBoxctl00_MainContent_txtName
Buttonctl00_MainContent_btnSubmit
+

This is essential when your JavaScript or CSS targets the full ctl00_-prefixed IDs that Web Forms generated.

+

Migration Example

+

Before (Web Forms): +

<form id="form1" runat="server">
+    <asp:Panel ID="MainContent" runat="server">
+        <asp:TextBox ID="txtEmail" runat="server" />
+        <asp:Button ID="btnRegister" runat="server" Text="Register" />
+    </asp:Panel>
+</form>
+
+<script>
+    // JavaScript targeting Web Forms IDs
+    var email = document.getElementById('ctl00_MainContent_txtEmail');
+    var btn = document.getElementById('ctl00_MainContent_btnRegister');
+</script>
+

+

After (Blazor): +

<NamingContainer ID="MainContent" UseCtl00Prefix="true">
+    <TextBox ID="txtEmail" />
+    <Button ID="btnRegister" Text="Register" />
+</NamingContainer>
+
+<script>
+    // JavaScript unchanged — same IDs as before
+    var email = document.getElementById('ctl00_MainContent_txtEmail');
+    var btn = document.getElementById('ctl00_MainContent_btnRegister');
+</script>
+

+

Relationship to WebFormsPage

+

WebFormsPage inherits from NamingContainer and adds theme/skin cascading. Use the table below to choose the right component:

+ + + + + + + + + + + + + + + + + + + + + + + +
ComponentNaming ScopeThemingWhen to Use
NamingContainer✅❌Nested naming scopes within a page, or when theming is not needed
WebFormsPage✅✅Layout-level wrapper providing both naming scope and theme support
+

If you only need ID prefixing — for example, to scope a subsection of a page — use NamingContainer. If you need the full Web Forms Page-level experience (naming + themes), use WebFormsPage in your layout.

+

Moving On

+

As you complete your migration away from Web Forms patterns:

+
    +
  1. Replace string-based IDs with @ref — Blazor's component references are type-safe and don't depend on naming conventions
    2. +
  2. Remove ctl00 prefixes — Update JavaScript to use simpler IDs, then set UseCtl00Prefix="false" or remove NamingContainer entirely
    3. +
  3. Use CSS classes instead of ID selectors — CSS class selectors are more resilient and don't depend on component hierarchy
    4. +
+

See Also

+
    +
  • ID Rendering — How component IDs work across the library
    • +
  • WebFormsPage — Combined naming container and theme wrapper
    • +
  • ViewState — How ViewState is emulated in Blazor
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/PageService/index.html b/site/UtilityFeatures/PageService/index.html new file mode 100644 index 000000000..2c17216a0 --- /dev/null +++ b/site/UtilityFeatures/PageService/index.html @@ -0,0 +1,5532 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page System - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Page System

+

The Page system in BlazorWebFormsComponents recreates the System.Web.UI.Page code-behind experience for Blazor. It lets converted pages use Page.Title, Page.MetaDescription, Page.MetaKeywords, and if (!IsPostBack) with zero syntax changes from Web Forms.

+

Original Microsoft implementation: System.Web.UI.Page

+

Background

+

In ASP.NET Web Forms, the Page object provided a central place for page-level properties and functionality. Every code-behind file inherited from System.Web.UI.Page, giving automatic access to Page.Title, Page.MetaDescription, Page.MetaKeywords, and IsPostBack:

+
// Web Forms code-behind (.aspx.cs)
+public partial class Products : System.Web.UI.Page
+{
+    protected void Page_Load(object sender, EventArgs e)
+    {
+        if (!IsPostBack)
+        {
+            Page.Title = "Products - Contoso";
+            Page.MetaDescription = "Browse our product catalog";
+            Page.MetaKeywords = "products, catalog, shopping";
+        }
+    }
+}
+
+

These properties automatically updated the HTML <title> and <meta> elements in the rendered page.

+

Architecture

+

The Page system uses three complementary pieces:

+
┌──────────────────────┐       ┌──────────────────┐       ┌──────────────────┐
+│   WebFormsPageBase   │       │   IPageService    │       │  WebFormsPage    │
+│   (code-behind API)  │──────▶│   (scoped bridge) │──────▶│  (layout wrapper)│
+│                      │ writes│                   │ reads │                  │
+│ • Title              │       │ • Title           │       │ • <PageTitle>    │
+│ • MetaDescription    │       │ • MetaDescription │       │ • <meta> tags    │
+│ • MetaKeywords       │       │ • MetaKeywords    │       │ • NamingContainer│
+│ • IsPostBack         │       │ • Change events   │       │ • ThemeProvider  │
+│ • Page (self-ref)    │       │                   │       │                  │
+└──────────────────────┘       └──────────────────┘       └──────────────────┘
+     Your pages inherit              DI service               In your layout
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
PieceRoleWhere it lives
WebFormsPageBaseAbstract base class for converted pages. Provides Title, MetaDescription, MetaKeywords, IsPostBack, and Page (self-reference). This is the code-behind API your pages inherit.@inherits in _Imports.razor
IPageService / PageServiceScoped service that bridges the base class and the renderer. Property setters fire change events.Registered by AddBlazorWebFormsComponents()
WebFormsPageUnified layout wrapper that provides NamingContainer (ID mangling), ThemeProvider (skin cascading), AND page head rendering (<PageTitle> + <meta> tags). Subscribes to IPageService events.<WebFormsPage> wrapping @Body in layout
+

Key point: WebFormsPageBase and WebFormsPage are complementary, not redundant. WebFormsPageBase writes data to IPageService; WebFormsPage reads from IPageService and renders HTML. Both are needed.

+
+

All-in-one layout component

+

<WebFormsPage> combines naming, theming, and head rendering into a single component. You no longer need a separate <Page /> component — <WebFormsPage> handles everything.

+
+

One-Time Setup

+

Two things need to happen once in your application:

+

1. Register the service (Program.cs)

+
// Program.cs
+builder.Services.AddBlazorWebFormsComponents();
+
+

This registers IPageService as a scoped service.

+

2. Add WebFormsPage to your layout

+
@* MainLayout.razor *@
+@inherits LayoutComponentBase
+
+<WebFormsPage ID="MainContent">
+    @Body
+</WebFormsPage>
+
+

<WebFormsPage> provides three features in one component:

+
    +
  • NamingContainer — Web Forms-style ctl00 ID mangling for child controls
    • +
  • ThemeProvider — Cascades ThemeConfiguration to child components (optional Theme parameter)
    • +
  • Page head rendering — Subscribes to IPageService and renders <PageTitle> + <meta> tags
    • +
+
+

RenderPageHead parameter

+

If you need to handle head rendering separately (e.g., with a standalone <Page /> component), set RenderPageHead="false" on <WebFormsPage> to disable head rendering.

+
+
+

Standalone Page.razor

+

The <BlazorWebFormsComponents.Page /> component is still available as a standalone head renderer for apps that don't use <WebFormsPage>. However, when using <WebFormsPage>, the standalone <Page /> is unnecessary — don't use both, or you'll get duplicate head content.

+
+

Primary Approach: WebFormsPageBase

+

For converted Web Forms pages, inherit from WebFormsPageBase. This is the recommended approach because it preserves your existing code-behind patterns with zero syntax changes.

+

Setup

+

Add to your _Imports.razor:

+
@inherits BlazorWebFormsComponents.WebFormsPageBase
+
+
+

Scope

+

The @inherits directive applies to all .razor files in the same directory and subdirectories. If only some pages need it, place a separate _Imports.razor in the pages folder.

+
+

Usage

+

With WebFormsPageBase as your base class, Web Forms code-behind patterns work unchanged:

+
@page "/products"
+
+<h1>Products</h1>
+
+@code {
+    protected override void OnInitialized()
+    {
+        if (!IsPostBack)
+        {
+            Page.Title = "Products - Contoso";
+            Page.MetaDescription = "Browse our product catalog";
+            Page.MetaKeywords = "products, catalog, shopping";
+        }
+    }
+}
+
+

This works because:

+
    +
  • Page returns this (a self-reference), so Page.Title resolves to this.Title
    • +
  • Title, MetaDescription, and MetaKeywords delegate to the injected IPageService
    • +
  • IsPostBack always returns false — so if (!IsPostBack) blocks always execute, matching first-load behavior
    • +
+

Properties Available

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
TitlestringGets/sets the page title. Delegates to IPageService.Title.
MetaDescriptionstringGets/sets the meta description. Delegates to IPageService.MetaDescription.
MetaKeywordsstringGets/sets the meta keywords. Delegates to IPageService.MetaKeywords.
IsPostBackboolAlways returns false. Blazor has no postback model.
PageWebFormsPageBaseReturns this. Enables Page.Title syntax.
+

Properties NOT Available

+

The following System.Web.UI.Page members are deliberately omitted to encourage proper Blazor migration:

+
    +
  • Page.Request — Use NavigationManager or HttpContext instead
    • +
  • Page.Response — Use NavigationManager.NavigateTo() for redirects
    • +
  • Page.Session — Use ProtectedSessionStorage, ProtectedLocalStorage, or a scoped service
    • +
  • Page.Server — Use standard .NET APIs (Path, HttpUtility, etc.)
    • +
  • Page.Cache — Use IMemoryCache or IDistributedCache
    • +
+
+

Dead Code: if (IsPostBack)

+

Code guarded by if (IsPostBack) (without !) will never execute because IsPostBack is always false. During migration, search for if (IsPostBack) (without the negation) and flag those blocks for review — they likely contain logic that needs to be reimplemented as Blazor event handlers.

+
+

Secondary Approach: Direct IPageService Injection

+

For components that don't inherit from WebFormsPageBase, you can inject IPageService directly. This is useful for:

+
    +
  • Non-page components that need to set page metadata
    • +
  • Shared components used across pages
    • +
  • Developers who prefer explicit dependency injection
    • +
+
@inject IPageService PageService
+
+@code {
+    protected override void OnInitialized()
+    {
+        PageService.Title = "My Page Title";
+        PageService.MetaDescription = "Description for search engines";
+        PageService.MetaKeywords = "keyword1, keyword2";
+    }
+}
+
+
+

Naming Convention

+

If you name the injection @inject IPageService Page, the syntax matches Web Forms exactly: Page.Title = "...". However, this may conflict with the Page property on WebFormsPageBase, so use PageService as the variable name when both patterns appear in the same project.

+
+

Web Forms Usage

+

In Web Forms, the Page object was automatically available in all code-behind files:

+
<%@ Page Language="C#" Title="Static Title" 
+         MetaDescription="Page description" 
+         MetaKeywords="keyword1, keyword2" %>
+
+
// Code-behind (.aspx.cs)
+public partial class MyPage : System.Web.UI.Page
+{
+    protected void Page_Load(object sender, EventArgs e)
+    {
+        if (!IsPostBack)
+        {
+            Page.Title = GetTitleFromDatabase();
+            Page.MetaDescription = GetDescriptionFromDatabase();
+            Page.MetaKeywords = GetKeywordsFromDatabase();
+        }
+    }
+}
+
+

Migration Path

+

Before (Web Forms)

+
<%@ Page Language="C#" MasterPageFile="~/Site.Master"
+         MetaDescription="Customer details page"
+         MetaKeywords="customer, details, crm"
+         CodeBehind="CustomerDetails.aspx.cs"
+         Inherits="MyApp.CustomerDetails" %>
+
+
// CustomerDetails.aspx.cs
+public partial class CustomerDetails : System.Web.UI.Page
+{
+    protected void Page_Load(object sender, EventArgs e)
+    {
+        if (!IsPostBack)
+        {
+            var customer = GetCustomer(Request.QueryString["id"]);
+            Page.Title = "Customer Details - " + customer.Name;
+            Page.MetaDescription = $"View details for {customer.Name}";
+        }
+    }
+}
+
+

After (Blazor with WebFormsPageBase)

+
@page "/customer/{Id:int}"
+
+<h1>Customer Details</h1>
+
+@if (customer != null)
+{
+    <p>@customer.Name</p>
+}
+
+@code {
+    [Parameter]
+    public int Id { get; set; }
+
+    private Customer? customer;
+
+    protected override async Task OnInitializedAsync()
+    {
+        if (!IsPostBack)
+        {
+            customer = await GetCustomer(Id);
+            Page.Title = "Customer Details - " + customer.Name;
+            Page.MetaDescription = $"View details for {customer.Name}";
+            Page.MetaKeywords = "customer, details, crm";
+        }
+    }
+}
+
+

The only changes from the original code-behind:

+
    +
  1. Removed System.Web.UI.Page inheritance (replaced by WebFormsPageBase via _Imports.razor)
    2. +
  2. Changed Request.QueryString["id"] to a Blazor [Parameter]
    3. +
  3. Made the method async (optional — depends on data access)
    4. +
+

Everything else — if (!IsPostBack), Page.Title, Page.MetaDescription — works unchanged.

+

Features

+

Title Property

+
    +
  • Get/Set: Read and write the page title dynamically
    • +
  • Event-Driven: TitleChanged event fires when title is updated
    • +
  • Reactive: The Page.razor component automatically updates the browser title when the property changes
    • +
+

MetaDescription Property

+
    +
  • Get/Set: Read and write the meta description dynamically
    • +
  • SEO-Friendly: Appears in search engine results (recommended 150-160 characters)
    • +
  • Event-Driven: MetaDescriptionChanged event fires when description is updated
    • +
  • Reactive: The Page.razor component automatically updates the <meta> tag when the property changes
    • +
+

MetaKeywords Property

+
    +
  • Get/Set: Read and write the meta keywords dynamically
    • +
  • SEO Support: Helps categorize page content for search engines
    • +
  • Event-Driven: MetaKeywordsChanged event fires when keywords are updated
    • +
  • Reactive: The Page.razor component automatically updates the <meta> tag when the property changes
    • +
+

Future Extensibility

+

The IPageService interface can be extended in future versions to support additional Page object features:

+
    +
  • Open Graph meta tags for social media
    • +
  • Page-level client script registration
    • +
  • Page-level CSS registration
    • +
  • Custom meta tags
    • +
+

Key Differences from Web Forms

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web FormsBlazor (WebFormsPageBase)Blazor (inject IPageService)Notes
Page.TitlePage.Title ✅PageService.TitleIdentical syntax with base class
Page.MetaDescriptionPage.MetaDescription ✅PageService.MetaDescription.NET 4.0+
Page.MetaKeywordsPage.MetaKeywords ✅PageService.MetaKeywords.NET 4.0+
if (!IsPostBack)if (!IsPostBack) ✅N/AAlways false — block always runs
Inherits System.Web.UI.PageInherits WebFormsPageBaseNo inheritance neededSet via _Imports.razor
Available automaticallyAvailable automaticallyMust inject IPageServiceBase class injects for you
Page.Request, Page.ResponseNot availableNot availableUse Blazor equivalents
+

Moving On

+

While the Page system provides familiar Web Forms compatibility, consider these Blazor-native approaches as you refactor:

+

For Static Metadata

+

Use the built-in Blazor components directly:

+
@page "/about"
+
+<PageTitle>About Us - My Company</PageTitle>
+<HeadContent>
+    <meta name="description" content="Learn about our company" />
+    <meta name="keywords" content="about, company, team" />
+</HeadContent>
+
+<h1>About Us</h1>
+
+

For Dynamic Metadata

+

The Page system approach is appropriate when: +- Metadata depends on data loaded asynchronously +- Metadata changes based on user actions +- Metadata is set in response to events +- You want Web Forms-style programmatic control

+

For simpler scenarios, you can use built-in Blazor components with bound variables:

+
<PageTitle>@currentTitle</PageTitle>
+<HeadContent>
+    <meta name="description" content="@currentDescription" />
+</HeadContent>
+
+@code {
+    private string currentTitle = "Default Title";
+    private string currentDescription = "Default description";
+
+    private void UpdateTitle(string newTitle)
+    {
+        currentTitle = newTitle;
+    }
+}
+
+

Best Practices

+
    +
  1. Set Title Early: Set the title in OnInitializedAsync or OnParametersSet to ensure it's available before first render
    2. +
  2. SEO Considerations: Provide meaningful, descriptive titles for better search engine optimization
    3. +
  3. User Context: Include relevant context in the title (e.g., customer name, product name)
    4. +
  4. Length: Keep titles under 60 characters for optimal display in browser tabs and search results
    5. +
  5. Consistent Pattern: Use a consistent title format across your application (e.g., "Page Name - Site Name")
    6. +
  6. One Renderer: Place <BlazorWebFormsComponents.Page /> in the layout once — do not add it to individual pages
    7. +
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/ResponseRedirect/index.html b/site/UtilityFeatures/ResponseRedirect/index.html new file mode 100644 index 000000000..ad8dee149 --- /dev/null +++ b/site/UtilityFeatures/ResponseRedirect/index.html @@ -0,0 +1,4859 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Response.Redirect - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Response.Redirect Shim

+

The ResponseShim class provides compatibility with the ASP.NET Web Forms Response.Redirect() pattern. It wraps Blazor's NavigationManager so that migrated code-behind using Response.Redirect("~/Products.aspx") compiles and navigates correctly without rewriting.

+

Original Microsoft implementation: https://docs.microsoft.com/en-us/dotnet/api/system.web.httpresponse.redirect?view=netframework-4.8

+

Background

+

In ASP.NET Web Forms, server-side redirects were performed through the Response object:

+
// Web Forms code-behind
+protected void btnSearch_Click(object sender, EventArgs e)
+{
+    Response.Redirect("~/Products.aspx");
+    Response.Redirect("~/Products/Details.aspx?id=5", false);
+    Response.Redirect("~/Admin/Dashboard.aspx", true);
+}
+
+

The Response object was available on every Page and UserControl via the inherited HttpResponse property.

+

Blazor Implementation

+

In Blazor, navigation is handled by NavigationManager.NavigateTo(). The ResponseShim bridges this gap by:

+
    +
  1. Stripping ~/ prefix — Converts ~/path to /path (virtual path resolution)
    2. +
  2. Stripping .aspx extension — Converts /path.aspx to /path (Blazor uses extensionless routes)
    3. +
  3. Ignoring endResponse — The second parameter has no meaning in Blazor's component model
    4. +
+

Availability

+

ResponseShim is automatically available when your page inherits from WebFormsPageBase:

+
@inherits WebFormsPageBase
+
+@code {
+    private void HandleClick()
+    {
+        // Works exactly like Web Forms
+        Response.Redirect("~/Products.aspx");
+    }
+}
+
+

Web Forms Usage

+
// Common Web Forms patterns
+Response.Redirect("~/Products.aspx");
+Response.Redirect("~/Products/Details.aspx?id=" + productId);
+Response.Redirect("~/Login.aspx", true);   // endResponse = true
+Response.Redirect("~/Dashboard.aspx", false); // endResponse = false
+
+

Blazor Usage

+
@inherits WebFormsPageBase
+
+<Button Text="Go to Products" OnClick="GoToProducts" />
+<Button Text="View Details" OnClick="ViewDetails" />
+
+@code {
+    private int _selectedProductId = 5;
+
+    private void GoToProducts()
+    {
+        // ~/Products.aspx → /Products
+        Response.Redirect("~/Products.aspx");
+    }
+
+    private void ViewDetails()
+    {
+        // Query strings are preserved
+        Response.Redirect($"~/Products/Details.aspx?id={_selectedProductId}");
+    }
+}
+
+

URL Transformations

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web Forms URLBlazor URLNotes
~/Products.aspx/Products~/ stripped, .aspx removed
~/Admin/Dashboard.aspx/Admin/DashboardPath structure preserved
~/Products.aspx?id=5/Products?id=5Query strings preserved
/Products/ProductsAlready-clean URLs pass through
~//Root redirect
+

Migration Path

+

The ResponseShim handles the most common redirect patterns. For each pattern:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Web Forms PatternResponseShim SupportNotes
Response.Redirect(url)✅ FullPrimary use case
Response.Redirect(url, endResponse)✅ CompilesendResponse is ignored
Response.RedirectPermanent(url)❌ Not supportedUse NavigationManager.NavigateTo() directly
Response.Write(html)❌ Not supportedNot applicable in Blazor
Response.StatusCode = 404❌ Not supportedUse middleware or NavigationManager
+

Moving On

+

Response.Redirect() is a migration bridge. As you refactor:

+
    +
  1. Replace with NavigationManager — Inject NavigationManager and call NavigateTo() directly
    2. +
  2. Remove .aspx from route references — Update string constants to use clean Blazor routes
    3. +
  3. Remove ~/ prefixes — Use absolute paths (/Products) or relative navigation
    4. +
+
@* Before (migration shim) *@
+@inherits WebFormsPageBase
+@code {
+    void Navigate() => Response.Redirect("~/Products.aspx");
+}
+
+@* After (native Blazor) *@
+@inject NavigationManager Nav
+@code {
+    void Navigate() => Nav.NavigateTo("/Products");
+}
+
+

See Also

+
    +
  • WebFormsPage — Page-level base class providing the Response property
    • +
  • Page System — Title, MetaDescription, and other page-level services
    • +
  • L2 Automation Shims — Overview of all migration automation features
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/ServiceRegistration/index.html b/site/UtilityFeatures/ServiceRegistration/index.html new file mode 100644 index 000000000..e37827c8f --- /dev/null +++ b/site/UtilityFeatures/ServiceRegistration/index.html @@ -0,0 +1,4673 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Service Registration - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Service Registration

+

BlazorWebFormsComponents provides a single extension method to register all required services in your ASP.NET Core application. This is the recommended way to set up the library.

+

Setup

+

In your Program.cs, call AddBlazorWebFormsComponents() on your service collection:

+
var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddBlazorWebFormsComponents();
+
+// ... rest of your setup
+
+

That's it — one line handles everything the library needs.

+

What Gets Registered

+

The AddBlazorWebFormsComponents() method registers the following services:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ServiceLifetimePurpose
IHttpContextAccessorSingletonUsed by BaseWebFormsComponent for route URL helpers and request context. Registered via reflection so the library doesn't need a framework reference.
BlazorWebFormsJsInteropScopedHandles automatic JavaScript module loading for features like OnClientClick and page title management.
IPageService / PageServiceScopedProvides the page lifecycle and metadata services used by WebFormsPageBase.
+

IHttpContextAccessor — Automatic Registration

+

In earlier versions, consuming applications had to manually call services.AddHttpContextAccessor() in their Program.cs. This is no longer required.

+

The library now registers IHttpContextAccessor automatically using reflection. Since every ASP.NET Core application has the Microsoft.AspNetCore.Http assembly loaded at runtime, the reflection call succeeds transparently. If the assembly isn't available (e.g., in a unit test host), the call is silently skipped — no exceptions are thrown.

+
+

Migration Tip

+

If your Program.cs already has services.AddHttpContextAccessor(), you can safely remove it. The library's registration uses TryAddSingleton internally, so duplicate calls are harmless but unnecessary.

+
+

Usage with WebFormsPageBase

+

If your pages inherit from WebFormsPageBase (the recommended base class for migrated pages), the services registered here provide the underlying infrastructure:

+
@* In your _Imports.razor *@
+@inherits BlazorWebFormsComponents.WebFormsPageBase
+
+@* Your pages automatically get access to: *@
+@* - Page.Title (via IPageService) *@
+@* - Request context (via IHttpContextAccessor) *@
+@* - NamingContainer support *@
+@* - Theme provider integration *@
+
+

See WebFormsPage for more details on the page base class.

+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/StylingComponents/index.html b/site/UtilityFeatures/StylingComponents/index.html new file mode 100644 index 000000000..ad70f89d3 --- /dev/null +++ b/site/UtilityFeatures/StylingComponents/index.html @@ -0,0 +1,5531 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Styling Components - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

Styling Components

+

Style sub-components are special Blazor components that define the appearance of rows, headers, footers, and other UI elements within data controls and complex layout controls. They use the cascading parameter pattern to propagate styling configuration from parent controls to their child elements.

+

The library includes 66 style sub-components used across GridView, DetailsView, DataList, FormView, DataGrid, Calendar, Menu, TreeView, and Login controls. This documentation explains how they work and how to use them when migrating from Web Forms.

+

Overview

+

In Web Forms, properties like HeaderStyle, RowStyle, and AlternatingRowStyle accepted a TableItemStyle object that could be configured:

+
<asp:GridView ID="gvCustomers" runat="server">
+    <HeaderStyle BackColor="Navy" ForeColor="White" Font-Bold="true" />
+    <RowStyle BackColor="White" />
+    <AlternatingRowStyle BackColor="LightGray" />
+</asp:GridView>
+
+

These style properties accepted inline configuration and rendered CSS styles to the corresponding HTML elements.

+

In Blazor, the same styles are applied using style sub-components that accept the same parameters and apply styles in the same way, using the cascading parameter pattern:

+
<GridView ItemsSource="customers">
+    <GridViewHeaderStyle BackColor="Navy" ForeColor="White" Font-Bold="true" />
+    <GridViewRowStyle BackColor="White" />
+    <GridViewAlternatingRowStyle BackColor="LightGray" />
+</GridView>
+
+

How Style Sub-Components Work

+

Style sub-components inherit from UiStyle or UiTableItemStyle base classes and use the cascading parameter pattern to pass styling configuration to their parent control:

+
    +
  1. Style Definition: A style sub-component (e.g., <GridViewHeaderStyle>) is declared as a child of a data control
    2. +
  2. Style Object Creation: The parent control creates a style object (e.g., HeaderStyle property) and registers it
    3. +
  3. Cascading Parameter: The parent control cascades the style object to all style sub-components as a cascading parameter
    4. +
  4. Style Configuration: The style sub-component applies its parameters (BackColor, ForeColor, BorderWidth, etc.) to the cascaded style object
    5. +
  5. Rendering: When the parent control renders, it applies the configured styles to the appropriate HTML elements
    6. +
+

Common Style Parameters

+

All style sub-components support a common set of parameters for controlling appearance:

+

Color and Border Properties

+
    +
  • BackColor: Background color (any named color, hex value, or RGB)
    • +
  • ForeColor: Text/foreground color
    • +
  • BorderColor: Border color
    • +
  • BorderStyle: Border style (Solid, Dotted, Dashed, Double, Groove, Ridge, Inset, Outset)
    • +
  • BorderWidth: Border width (pixels or units)
    • +
+

Sizing Properties

+
    +
  • Width: Element width (pixels, percentage, or units)
    • +
  • Height: Element height (pixels, percentage, or units)
    • +
+

Text Properties

+
    +
  • CssClass: CSS class name(s) to apply to the element
    • +
  • Font-Bold: Apply bold font weight
    • +
  • Font-Italic: Apply italic font style
    • +
  • Font-Names: Comma-separated font family names
    • +
  • Font-Size: Font size (pixels or units)
    • +
  • Font-Underline: Apply text underline
    • +
  • Font-Strikeout: Apply strikethrough
    • +
+

Table Cell Properties (Table Item Styles Only)

+
    +
  • HorizontalAlign: Text alignment (Left, Center, Right, Justify)
    • +
  • VerticalAlign: Vertical alignment (Top, Middle, Bottom)
    • +
  • Wrap: Whether text wraps in the cell (default: true)
    • +
+

Additional Attributes

+
    +
  • AdditionalAttributes: Capture any unmatched attributes for direct HTML styling
    • +
+

Style Sub-Component Categories

+

Style sub-components fall into several categories based on which controls use them:

+

GridView Styles

+
    +
  • <GridViewHeaderStyle> — Header row styling
    • +
  • <GridViewFooterStyle> — Footer row styling
    • +
  • <GridViewRowStyle> — Data row styling
    • +
  • <GridViewAlternatingRowStyle> — Alternating row styling
    • +
  • <GridViewSelectedRowStyle> — Selected/highlighted row styling
    • +
  • <GridViewEditRowStyle> — Edit mode row styling
    • +
  • <GridViewEmptyDataRowStyle> — Empty data message styling
    • +
  • <GridViewPagerStyle> — Pager controls styling
    • +
+

DetailsView Styles

+
    +
  • <DetailsViewHeaderStyle> — Header styling
    • +
  • <DetailsViewFooterStyle> — Footer styling
    • +
  • <DetailsViewRowStyle> — Field row styling
    • +
  • <DetailsViewAlternatingRowStyle> — Alternating field row styling
    • +
  • <DetailsViewEditRowStyle> — Edit mode row styling
    • +
  • <DetailsViewInsertRowStyle> — Insert mode row styling
    • +
  • <DetailsViewCommandRowStyle> — Command button row styling
    • +
  • <DetailsViewFieldHeaderStyle> — Field label column styling
    • +
  • <DetailsViewEmptyDataRowStyle> — Empty data message styling
    • +
  • <DetailsViewPagerStyle> — Pager controls styling
    • +
+

FormView Styles

+
    +
  • <FormViewHeaderStyle> — Header styling
    • +
  • <FormViewFooterStyle> — Footer styling
    • +
  • <FormViewRowStyle> — Content row styling
    • +
  • <FormViewAlternatingRowStyle> — Alternating row styling
    • +
  • <FormViewEditRowStyle> — Edit mode styling
    • +
  • <FormViewInsertRowStyle> — Insert mode styling
    • +
  • <FormViewEmptyDataRowStyle> — Empty data message styling
    • +
  • <FormViewPagerStyle> — Pager controls styling
    • +
+

DataList Styles

+
    +
  • <AlternatingItemStyle> — Alternating item styling
    • +
+

DataGrid Styles

+
    +
  • <DataGridHeaderStyle> — Header styling
    • +
  • <DataGridFooterStyle> — Footer styling
    • +
  • <DataGridItemStyle> — Item styling
    • +
  • <DataGridAlternatingItemStyle> — Alternating item styling
    • +
  • <DataGridEditItemStyle> — Edit mode styling
    • +
  • <DataGridSelectedItemStyle> — Selected item styling
    • +
  • <DataGridPagerStyle> — Pager styling
    • +
+

Calendar Styles

+
    +
  • <CalendarTitleStyle> — Month/year title styling
    • +
  • <CalendarNextPrevStyle> — Next/previous navigation buttons styling
    • +
  • <CalendarDayHeaderStyle> — Day-of-week header styling
    • +
  • <CalendarDayStyle> — Regular day cell styling
    • +
  • <CalendarWeekendDayStyle> — Weekend day cell styling
    • +
  • <CalendarSelectedDayStyle> — Selected date cell styling
    • +
  • <CalendarTodayDayStyle> — Today's date cell styling
    • +
  • <CalendarOtherMonthDayStyle> — Other month's dates styling
    • +
  • <CalendarSelectorStyle> — Month/year selector styling
    • +
+ +
    +
  • <MenuItemStyle> — Menu item styling
    • +
  • <SeparatorStyle> — Menu separator styling
    • +
+

TreeView Styles

+
    +
  • <TreeViewNodeStyle> — General node styling
    • +
  • <TreeViewRootNodeStyle> — Root-level node styling
    • +
  • <TreeViewParentNodeStyle> — Parent node styling
    • +
  • <TreeViewLeafNodeStyle> — Leaf node styling
    • +
  • <TreeViewSelectedNodeStyle> — Selected node styling
    • +
  • <TreeViewHoverNodeStyle> — Hover state styling
    • +
+

Login Control Styles

+
    +
  • <CheckBoxStyle> — Checkbox styling
    • +
  • <HyperLinkStyle> — Hyperlink styling
    • +
  • <LabelStyle> — Label styling
    • +
  • <TextBoxStyle> — Text input styling
    • +
  • <LoginButtonStyle> — Button styling
    • +
  • <InstructionTextStyle> — Instruction text styling
    • +
  • <FailureTextStyle> — Error message styling
    • +
  • <SuccessTextStyle> — Success message styling
    • +
  • <TitleTextStyle> — Title text styling
    • +
  • <ValidatorTextStyle> — Validator message styling
    • +
+

Usage Examples

+

GridView with Styled Rows

+

Before (Web Forms): +

<asp:GridView ID="gvProducts" runat="server" DataSource="products">
+    <HeaderStyle BackColor="Navy" ForeColor="White" Font-Bold="true" HorizontalAlign="Center" />
+    <RowStyle BackColor="White" />
+    <AlternatingRowStyle BackColor="LightGray" />
+    <SelectedRowStyle BackColor="Yellow" ForeColor="Black" />
+    <Columns>
+        <asp:BoundField DataField="ProductName" HeaderText="Product" />
+        <asp:BoundField DataField="Price" HeaderText="Price" DataFormatString="{0:C}" />
+    </Columns>
+</asp:GridView>
+

+

After (Blazor): +

<GridView ItemsSource="products">
+    <GridViewHeaderStyle BackColor="Navy" ForeColor="White" Font-Bold="true" HorizontalAlign="Center" />
+    <GridViewRowStyle BackColor="White" />
+    <GridViewAlternatingRowStyle BackColor="LightGray" />
+    <GridViewSelectedRowStyle BackColor="Yellow" ForeColor="Black" />
+    <BoundColumn DataField="ProductName" HeaderText="Product" />
+    <BoundColumn DataField="Price" HeaderText="Price" DataFormatString="{0:C}" />
+</GridView>
+

+

Calendar with Themed Days

+

Before (Web Forms): +

<asp:Calendar ID="cal1" runat="server">
+    <TitleStyle BackColor="Navy" ForeColor="White" Font-Bold="true" />
+    <DayStyle BackColor="White" />
+    <WeekendDayStyle BackColor="LightGray" />
+    <SelectedDayStyle BackColor="Gold" ForeColor="Black" Font-Bold="true" />
+</asp:Calendar>
+

+

After (Blazor): +

<Calendar>
+    <CalendarTitleStyle BackColor="Navy" ForeColor="White" Font-Bold="true" />
+    <CalendarDayStyle BackColor="White" />
+    <CalendarWeekendDayStyle BackColor="LightGray" />
+    <CalendarSelectedDayStyle BackColor="Gold" ForeColor="Black" Font-Bold="true" />
+</Calendar>
+

+

DetailsView with Alternating Row Colors

+

Before (Web Forms): +

<asp:DetailsView ID="dvProduct" runat="server" DataSource="product">
+    <FieldHeaderStyle BackColor="LightGray" Font-Bold="true" />
+    <RowStyle BackColor="White" />
+    <AlternatingRowStyle BackColor="LightCyan" />
+</asp:DetailsView>
+

+

After (Blazor): +

<DetailsView ItemsSource="product">
+    <DetailsViewFieldHeaderStyle BackColor="LightGray" Font-Bold="true" />
+    <DetailsViewRowStyle BackColor="White" />
+    <DetailsViewAlternatingRowStyle BackColor="LightCyan" />
+</DetailsView>
+

+

TreeView with Node-Level Styling

+

Before (Web Forms): +

<asp:TreeView ID="tvMenu" runat="server">
+    <NodeStyle BackColor="White" ForeColor="Black" />
+    <RootNodeStyle BackColor="Navy" ForeColor="White" Font-Bold="true" />
+    <LeafNodeStyle BackColor="White" ForeColor="Black" />
+    <SelectedNodeStyle BackColor="Yellow" ForeColor="Black" />
+</asp:TreeView>
+

+

After (Blazor): +

<TreeView>
+    <TreeViewNodeStyle BackColor="White" ForeColor="Black" />
+    <TreeViewRootNodeStyle BackColor="Navy" ForeColor="White" Font-Bold="true" />
+    <TreeViewLeafNodeStyle BackColor="White" ForeColor="Black" />
+    <TreeViewSelectedNodeStyle BackColor="Yellow" ForeColor="Black" />
+</TreeView>
+

+

Login Control with Custom Styling

+

Before (Web Forms): +

<asp:Login ID="login1" runat="server">
+    <LoginButtonStyle BackColor="Navy" ForeColor="White" Font-Bold="true" />
+    <TextBoxStyle BorderWidth="1px" BorderColor="Gray" />
+    <LabelStyle Font-Bold="true" />
+    <FailureTextStyle ForeColor="Red" Font-Italic="true" />
+</asp:Login>
+

+

After (Blazor): +

<Login>
+    <LoginButtonStyle BackColor="Navy" ForeColor="White" Font-Bold="true" />
+    <TextBoxStyle BorderWidth="1px" BorderColor="Gray" />
+    <LabelStyle Font-Bold="true" />
+    <FailureTextStyle ForeColor="Red" Font-Italic="true" />
+</Login>
+

+

Migration Tips

+

When migrating from Web Forms:

+
    +
  1. Identify styled regions: Look for the <XxxStyle> properties in your Web Forms controls
    2. +
  2. Replace with Blazor equivalents: Use the corresponding <XxxStyle> components in your Blazor markup
    3. +
  3. Match parameter names: The parameter names are identical to Web Forms (BackColor, ForeColor, Font-Bold, etc.)
    4. +
  4. Test rendering: Verify that the rendered HTML matches your Web Forms output and that your existing CSS continues to work
    5. +
  5. Use CSS classes: For complex styling, consider using the CssClass parameter and moving styles to CSS files
    6. +
+

Style Object Architecture

+

The style system is built on several base classes:

+
    +
  • UiStyle: Base class for simple styles with color, border, sizing, and font properties
    • +
  • UiTableItemStyle: Extends UiStyle with horizontal alignment, vertical alignment, and text wrapping (used for grid/table rows)
    • +
  • Style: The C# model class that holds styled property values and renders CSS inline styles
    • +
+

When a style sub-component is configured, its parameters are passed to an internal Style object that: +- Validates property values +- Converts color and unit values to proper formats +- Generates CSS inline styles for rendering +- Provides the ToString() method to output the style attribute

+

Best Practices

+
    +
  1. Use Consistent Naming: Follow the "XxxControlYyyStyle" naming pattern for clarity (e.g., GridViewHeaderStyle, CalendarSelectedDayStyle)
    2. +
  2. Keep Styles Focused: Use each style sub-component for a single visual purpose (header row, alternating rows, etc.)
    3. +
  3. Avoid Inline Style Overuse: For complex layouts, consider using CSS classes instead of multiple inline style parameters
    4. +
  4. Test Visual Consistency: Ensure migrated styles match the original Web Forms appearance
    5. +
  5. Document Custom Styles: If you create custom controls with style sub-components, document which style sub-components they support
    6. +
  6. Consider Accessibility: Use sufficient color contrast in BackColor/ForeColor combinations for accessibility compliance
    7. +
+ +
    +
  • ID Rendering — Controlling element IDs for JavaScript integration
    • +
  • ViewState — Understanding state management for styled controls
    • +
  • Databinder — Data binding patterns within styled data controls
    • +
  • WebFormsPage — Full-page theming and naming container configuration
    • +
+

Common Issues and Solutions

+

Styles Not Applying

+

Problem: Style properties set but HTML doesn't show the styles.
+Solution: Ensure the style sub-component is declared as a child of the control. The parent control must recognize it as a cascading parameter receiver.

+

CSS Classes Not Working with Inline Styles

+

Problem: CssClass parameter doesn't override inline styles.
+Solution: Use CSS specificity rules or !important flags in your CSS to override inline styles if needed.

+

Font Parameters Not Recognized

+

Problem: Font-Bold, Font-Italic, etc., showing as "unmatched attributes."
+Solution: Use PascalCase with hyphens: Font-Bold="true", Font-Italic="true", Font-Names="Arial,Helvetica".

+
+

For complete working examples, see the samples in the repository's sample applications and migration test cases.

+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/ViewState/index.html b/site/UtilityFeatures/ViewState/index.html new file mode 100644 index 000000000..3080855e5 --- /dev/null +++ b/site/UtilityFeatures/ViewState/index.html @@ -0,0 +1,4699 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ViewState - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ViewState

+

One of the most abused and misunderstood features of ASP.NET Web Forms is ViewState. Originally designed to help stateful Visual Basic 6 Windows application developers migrate to the web, this feature delivered a lot of heartache to developers who didn't fully understand and limit its usage appropriately in their web applications. In Web Forms, every Page and every Control carries a ViewState object that contains the state of the Control or Page at the time of request, serialized and output as an HTML hidden input tag. Without proper diligence in selecting which controls and features need their state tracked, many applications found this HTML tag fill up with megabytes of serialized code and slowing their applications.

+

Elsewhere in Web Forms, ViewState could be used as a key/value store to place data that should be remembered during the current fetch/post/retrieve cycle for a page. You would find syntax like the following in Pages and Controls to add the bar object with a key named foo:

+
ViewState.Add("foo", bar);
+
+

or to fetch the item named foo from ViewState:

+
ViewState["foo"]
+
+

It's a simple syntax and implements a typical Dictionary pattern. After the PreRender phase of a Page, the content would be serialized and inserted into an HTML hidden input so that it would be available when the Page was posted.

+

Implementation in BlazorWebFormsComponents

+

BlazorWebFormsComponents now provides ViewStateDictionary, a comprehensive implementation of ViewState that works seamlessly across rendering modes:

+
    +
  • SSR (Server-Side Rendering) — ViewState automatically serializes to a protected hidden form field for round-tripping through HTTP POSTs
    • +
  • ServerInteractive (Blazor WebSocket) — ViewState persists in component memory for the lifetime of the component instance
    • +
+

This allows Web Forms patterns to migrate with minimal markup changes.

+

Quick Start

+
// Store a value
+ViewState["UserPreferences"] = new UserSettings { Theme = "Dark" };
+
+// Retrieve a value (null-safe)
+var prefs = ViewState["UserPreferences"];
+
+// Type-safe convenience method
+ViewState.Set<UserSettings>("UserPreferences", userSettings);
+UserSettings retrieved = ViewState.GetValueOrDefault<UserSettings>("UserPreferences", new());
+
+

Detecting Postbacks

+

Use the IsPostBack property to distinguish between first render and postback:

+
protected override void OnInitialized()
+{
+    if (!IsPostBack)
+    {
+        // First render: load initial data
+        LoadProducts();
+    }
+    else
+    {
+        // Postback: restore state from ViewState
+        RestoreState();
+    }
+}
+
+

Hidden Field Persistence (SSR Only)

+

When running in SSR, ViewState is automatically round-tripped through a protected hidden form field. Manually emit the field when needed:

+
<form method="post">
+    <TextBox ID="Name" @bind-Value="_name" />
+    <Button Text="Save" @onclick="OnSave" />
+
+    <RenderViewStateField />
+</form>
+
+

Moving On

+

ViewState is not a feature you should continue to use after migrating. While we have already eliminated the serializeation / deserialization performance issue with ViewState, we still recommend moving any storage you do with ViewState to class-scoped fields and properties that can be validated and strongly-typed. This will also reduce the boxing/unboxing performance issue that exists with ViewState.

+

You would define the property for Foo with a syntax similar to, substituting the proper type of bar for BarType:

+
protected BarType Foo { get; set; }
+
+

The interaction above would be updated to the following syntax in your component's class:

+
// Store bar for retrieval later
+Foo = bar;
+
+// Fetch bar for use
+bar = Foo;
+
+

See Also

+
    +
  • ViewState and PostBack Shim — Comprehensive guide covering ViewStateDictionary, mode-adaptive IsPostBack, hidden field persistence, and migration patterns
    • +
+ + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/ViewStateAndPostBack/index.html b/site/UtilityFeatures/ViewStateAndPostBack/index.html new file mode 100644 index 000000000..9f4cc7116 --- /dev/null +++ b/site/UtilityFeatures/ViewStateAndPostBack/index.html @@ -0,0 +1,6012 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ViewState and PostBack Shim - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ViewState and PostBack Shim

+

Overview

+

The ViewState and PostBack shim features enable seamless migration of ASP.NET Web Forms applications to Blazor by emulating the familiar ViewState dictionary and IsPostBack pattern. These features bridge the gap between traditional stateless HTTP POST workflows and Blazor's component-based stateful architecture.

+

Key Features

+
    +
  • ViewStateDictionary — A state management class that persists data across postbacks, with automatic serialization for SSR and in-memory storage for ServerInteractive mode
    • +
  • Mode-Adaptive IsPostBack — A property that automatically detects postback scenarios based on your render mode
    • +
  • Hidden Field Persistence — Automatic round-tripping of ViewState through protected form fields in SSR
    • +
  • Form State Continuity — Seamless state management across SSR and ServerInteractive transitions
    • +
+
+

ViewStateDictionary

+

What It Is

+

ViewStateDictionary is a dictionary-based state store that emulates the ASP.NET Web Forms ViewState pattern. It implements IDictionary<string, object?> with additional convenience methods for type-safe access.

+

In Web Forms, ViewState was serialized and embedded as a hidden field. In BlazorWebFormsComponents, ViewStateDictionary adapts to your rendering mode:

+
    +
  • SSR (StaticSSR) — Serializes to a protected hidden form field for round-tripping through HTTP POSTs
    • +
  • ServerInteractive — Persists in component instance memory (equivalent to a private field)
    • +
+

API Surface

+

Indexer (Dictionary Pattern)

+
// Store a value
+viewState["foo"] = bar;
+
+// Retrieve a value (returns null if missing, no KeyNotFoundException)
+object? value = viewState["foo"];
+
+

Type-Safe Convenience Methods

+
// Store with automatic type conversion
+ViewState.Set<string>("Name", "John");
+
+// Retrieve with optional default value
+string name = ViewState.GetValueOrDefault<string>("Name", "Anonymous");
+int count = ViewState.GetValueOrDefault<int>("Count", 0);
+
+

State Tracking

+
// Returns true if the dictionary has been modified
+internal bool IsDirty { get; }
+
+// Resets the dirty flag after serialization
+internal void MarkClean();
+
+

Serialization (SSR Hidden Field Round-Trip)

+
// Serialize to protected string for hidden form field
+internal string Serialize(IDataProtector protector);
+
+// Deserialize from protected string after form POST
+internal static ViewStateDictionary Deserialize(string protectedPayload, IDataProtector protector);
+
+// Merge state from another dictionary
+internal void LoadFrom(ViewStateDictionary other);
+
+

Usage Examples

+

Simple Counter (ServerInteractive)

+
@page "/counter"
+@inherits BaseWebFormsComponent
+
+<div>
+    <p>Count: @(ViewState.GetValueOrDefault<int>("Counter", 0))</p>
+    <Button Text="Increment" @onclick="OnIncrement" />
+</div>
+
+@code {
+    private void OnIncrement()
+    {
+        int count = ViewState.GetValueOrDefault<int>("Counter", 0);
+        ViewState.Set<int>("Counter", count + 1);
+    }
+}
+
+

Migration Note: In Blazor, prefer a simple int field instead:

+
private int counter = 0;
+
+private void OnIncrement()
+{
+    counter++;
+}
+
+

Form with Hidden Field Persistence (SSR)

+

This example shows how ViewStateDictionary round-trips through SSR form POSTs.

+

Web Forms (Before):

+
<%@ Page Language="C#" %>
+<form runat="server">
+    <asp:TextBox ID="ProductNameTextBox" runat="server" />
+    <asp:Button ID="AddButton" Text="Add" runat="server" OnClick="AddButton_Click" />
+    <asp:GridView ID="ProductsGrid" runat="server" />
+
+    <script runat="server">
+        protected void AddButton_Click(object sender, EventArgs e)
+        {
+            var products = (List<Product>)ViewState["Products"] ?? new();
+            products.Add(new Product { Name = ProductNameTextBox.Text });
+            ViewState["Products"] = products;
+            ProductsGrid.DataSource = products;
+            ProductsGrid.DataBind();
+        }
+    </script>
+</form>
+
+

Blazor SSR (After):

+
@page "/products"
+@inherits WebFormsPageBase
+
+<form method="post">
+    <TextBox ID="ProductNameTextBox" @bind-Value="_productName" />
+    <Button ID="AddButton" Text="Add" @onclick="OnAddProduct" />
+    <GridView ID="ProductsGrid" DataSource="@_products" AutoGenerateColumns="true" />
+
+    <RenderViewStateField />
+</form>
+
+@code {
+    private string _productName = "";
+    private List<Product> _products = new();
+
+    protected override void OnInitialized()
+    {
+        // Load products from ViewState if this is a postback
+        if (IsPostBack)
+        {
+            var stored = ViewState.GetValueOrDefault<List<Product>>("Products");
+            if (stored != null)
+            {
+                _products = stored;
+            }
+        }
+    }
+
+    private void OnAddProduct()
+    {
+        if (!string.IsNullOrEmpty(_productName))
+        {
+            _products.Add(new Product { Name = _productName });
+            ViewState.Set("Products", _products);
+            _productName = "";
+        }
+    }
+
+    public class Product
+    {
+        public string Name { get; set; }
+    }
+}
+
+

Multi-Step Wizard with IsPostBack

+
@page "/wizard"
+@inherits BaseWebFormsComponent
+
+@if (CurrentStep == 1)
+{
+    <WizardStep1 @ref="_step1" />
+}
+else if (CurrentStep == 2)
+{
+    <WizardStep2 @ref="_step2" />
+}
+else
+{
+    <WizardSummary Data="@_wizardData" />
+}
+
+<div>
+    @if (CurrentStep > 1)
+    {
+        <Button Text="Back" @onclick="GoBack" />
+    }
+    @if (CurrentStep < 3)
+    {
+        <Button Text="Next" @onclick="GoNext" />
+    }
+</div>
+
+@code {
+    private WizardData _wizardData = new();
+    private int CurrentStep
+    {
+        get => ViewState.GetValueOrDefault<int>("CurrentStep", 1);
+        set => ViewState.Set("CurrentStep", value);
+    }
+
+    protected override void OnInitialized()
+    {
+        // On first render (not postback), step is 1
+        // On postback, step is restored from ViewState
+        if (!IsPostBack)
+        {
+            _wizardData = new WizardData();
+            ViewState.Set("WizardData", _wizardData);
+        }
+        else
+        {
+            _wizardData = ViewState.GetValueOrDefault<WizardData>("WizardData", new());
+        }
+    }
+
+    private void GoNext()
+    {
+        CurrentStep++;
+        ViewState.Set("WizardData", _wizardData);
+    }
+
+    private void GoBack()
+    {
+        CurrentStep--;
+    }
+
+    public class WizardData
+    {
+        public string Step1Data { get; set; }
+        public string Step2Data { get; set; }
+    }
+}
+
+
+

IsPostBack — Mode-Adaptive Detection

+

What It Is

+

IsPostBack is a boolean property that indicates whether the current render is a postback or an initial render. It automatically adapts to your rendering mode:

+
    +
  • SSR (StaticSSR) — Returns true when the HTTP request method is POST (form submission)
    • +
  • ServerInteractive — Returns true after the first initialization, indicating a re-render triggered by user interaction or state change
    • +
+

Usage

+
protected override void OnInitialized()
+{
+    if (!IsPostBack)
+    {
+        // First render: load initial data
+        LoadData();
+    }
+    else
+    {
+        // Postback / re-render: restore from ViewState
+        RestoreState();
+    }
+}
+
+

API Reference

+

BaseWebFormsComponent

+
/// <summary>
+/// Returns <c>true</c> when the current request is a postback (form POST in SSR mode)
+/// or after the first initialization (in ServerInteractive mode).
+/// Matches the ASP.NET Web Forms <c>Page.IsPostBack</c> semantics.
+/// </summary>
+public bool IsPostBack { get; }
+
+

WebFormsPageBase

+
/// <summary>
+/// Always returns false. Blazor has no postback model.
+/// Exists so that if (!IsPostBack) { ... } compiles and executes correctly —
+/// the guarded block always runs, which is the correct behavior for
+/// OnInitialized (first-render) context.
+/// </summary>
+public bool IsPostBack => false;
+
+
+

Note: WebFormsPageBase.IsPostBack always returns false because pages in Blazor don't have HTTP-level postbacks. For page-level logic, use OnInitialized to detect first render instead.

+
+

IsPostBack Detection Mechanisms

+

In SSR Mode

+

When running in SSR (pre-render or StaticSSR), IsPostBack checks the HTTP request method:

+
if (HttpContextAccessor?.HttpContext is { } context)
+    return HttpMethods.IsPost(context.Request.Method);
+
+

This allows forms submitted with <form method="post"> to be detected as postbacks.

+

In ServerInteractive Mode

+

When running in ServerInteractive (interactive WebSocket mode), IsPostBack tracks component initialization:

+
private bool _hasInitialized = false;
+
+public bool IsPostBack => _hasInitialized;
+
+protected override void OnInitialized()
+{
+    if (!_hasInitialized)
+    {
+        _hasInitialized = true;
+    }
+}
+
+

This enables the first render check (if (!IsPostBack)) to work as in Web Forms, guarding one-time initialization code.

+
+

Hidden Field Persistence (SSR)

+

In SSR mode, ViewState is automatically serialized to a protected hidden form field and round-tripped through HTTP POSTs. This happens transparently without requiring manual form field management.

+

How It Works

+
    +
  1. Component Renders — During SSR pre-render, ViewStateDictionary serializes its contents
    2. +
  2. Hidden Field Emitted — A protected hidden input is rendered (encrypted, HMAC-signed)
    3. +
  3. Form Submits — User submits <form method="post">
    4. +
  4. Hidden Field Recovered — The form POST is processed, hidden field contents are decrypted and verified
    5. +
  5. ViewState Restored — The deserialized ViewState is loaded into the component instance
    6. +
  6. Component Re-renders — Business logic runs with ViewState state restored
    7. +
+

Security

+

ViewState is protected using IDataProtectionProvider:

+
    +
  • Encryption — AES-256 (via IDataProtector)
    • +
  • Authentication — HMAC-SHA256 signature (via IDataProtector)
    • +
  • No Tampering — Encrypted payload fails decryption if modified
    • +
+

If decryption fails (corrupted or tampered data), a graceful fallback occurs and an empty ViewState is used.

+

Manual Rendering (Advanced)

+

In rare cases, you may need to manually emit the ViewState hidden field. Use the RenderViewStateField utility:

+
<form method="post">
+    <TextBox ID="Name" @bind-Value="_name" />
+    <Button Text="Submit" @onclick="OnSubmit" />
+
+    <!-- Manually emit protected ViewState hidden field -->
+    <RenderViewStateField />
+</form>
+
+@code {
+    private string _name = "";
+
+    private void OnSubmit()
+    {
+        // Access ViewState as normal
+        ViewState.Set("LastName", _name);
+    }
+}
+
+
+

Note: RenderViewStateField is typically called automatically by the framework. Manual use is only needed for custom form layouts.

+
+
+

Form State Continuity (SSR ↔ ServerInteractive)

+

A common migration pattern is to start with SSR (traditional form posts) and gradually add interactive regions via ServerInteractive. ViewStateDictionary enables seamless state sharing:

+

Pattern: Progressive Enhancement

+
    +
  1. Start with SSR Form — Traditional HTML form with server-side POST handlers
    2. +
  2. Add Interactive Button — Replace a submit button with an interactive button
    3. +
  3. Share State — Both SSR form fields and interactive components read/write to ViewState
    4. +
  4. Transition Gradually — Move more logic to ServerInteractive over time
    5. +
+

Example: SSR Form + Interactive Counter

+
@page "/order"
+@inherits BaseWebFormsComponent
+@rendermode InteractiveServer
+
+<form method="post">
+    <div>
+        <Label Text="Item Count:" />
+        <!-- Update ViewState when user submits form -->
+        <TextBox ID="ItemCount" @bind-Value="_itemCountText" />
+    </div>
+
+    <div>
+        <!-- Or use interactive component to update ViewState -->
+        <Label Text="Quick Add:" />
+        <Button Text="+" @onclick="OnQuickAdd" />
+        <Label Text="@(ViewState.GetValueOrDefault<int>("QuickCount", 0))" />
+    </div>
+
+    <Button ID="SubmitButton" Text="Place Order" @onclick="OnSubmit" Type="submit" />
+</form>
+
+@code {
+    private string _itemCountText = "1";
+
+    protected override void OnInitialized()
+    {
+        if (IsPostBack)
+        {
+            // Form was submitted: read values posted by form fields
+            if (int.TryParse(_itemCountText, out var count))
+            {
+                ViewState.Set("ItemCount", count);
+            }
+        }
+        else
+        {
+            // First render: restore from ViewState or use defaults
+            var itemCount = ViewState.GetValueOrDefault<int>("ItemCount", 1);
+            _itemCountText = itemCount.ToString();
+        }
+    }
+
+    private void OnQuickAdd()
+    {
+        var count = ViewState.GetValueOrDefault<int>("QuickCount", 0);
+        ViewState.Set("QuickCount", count + 1);
+    }
+
+    private void OnSubmit()
+    {
+        // Save state for next postback
+        if (int.TryParse(_itemCountText, out var count))
+        {
+            ViewState.Set("ItemCount", count);
+        }
+    }
+}
+
+
+

Migration Path: From Web Forms ViewState

+

Before (Web Forms)

+
// Page code-behind
+public partial class ProductPage : System.Web.UI.Page
+{
+    protected void Page_Load()
+    {
+        if (!IsPostBack)
+        {
+            ViewState["Products"] = LoadProducts();
+        }
+    }
+
+    protected void AddButton_Click(object sender, EventArgs e)
+    {
+        var products = (List<Product>)ViewState["Products"];
+        products.Add(new Product { Name = ProductNameTextBox.Text });
+        ViewState["Products"] = products;
+    }
+}
+
+

After (Blazor SSR — Minimal Changes)

+
@page "/products"
+@inherits WebFormsPageBase
+
+<form method="post">
+    <TextBox ID="ProductNameTextBox" @bind-Value="_productName" />
+    <Button ID="AddButton" Text="Add" @onclick="OnAddProduct" />
+    <RenderViewStateField />
+</form>
+
+@code {
+    private string _productName = "";
+
+    protected override void OnInitialized()
+    {
+        if (!IsPostBack)
+        {
+            ViewState["Products"] = LoadProducts();
+        }
+    }
+
+    private void OnAddProduct()
+    {
+        var products = (List<Product>)ViewState["Products"];
+        products.Add(new Product { Name = _productName });
+        ViewState["Products"] = products;
+    }
+
+    private List<Product> LoadProducts() => new();
+
+    public class Product
+    {
+        public string Name { get; set; }
+    }
+}
+
+

After (Blazor ServerInteractive — Refactored)

+
@page "/products"
+@inherits BaseWebFormsComponent
+@rendermode InteractiveServer
+
+<div>
+    <TextBox ID="ProductNameTextBox" @bind-Value="_productName" />
+    <Button Text="Add" @onclick="OnAddProduct" />
+</div>
+
+@code {
+    private string _productName = "";
+    private List<Product> _products = new();
+
+    protected override void OnInitialized()
+    {
+        if (!IsPostBack)
+        {
+            _products = LoadProducts();
+        }
+    }
+
+    private void OnAddProduct()
+    {
+        if (!string.IsNullOrEmpty(_productName))
+        {
+            _products.Add(new Product { Name = _productName });
+            _productName = "";
+        }
+    }
+
+    private List<Product> LoadProducts() => new();
+
+    public class Product
+    {
+        public string Name { get; set; }
+    }
+}
+
+
+

Best Practices

+

✅ Do

+
    +
  • Use ViewState for state that survives postbacks — Ideal for SSR migration where forms round-trip
    • +
  • Use IsPostBack to guard one-time initialization — Load data on first render, restore on postback
    • +
  • Prefer typed fields for new code — private int counter is clearer than ViewState["counter"]
    • +
  • Scope ViewState to the component — Each component instance has its own ViewState
    • +
  • Use GetValueOrDefault<T> — Type-safe retrieval with optional defaults
    • +
+

❌ Don't

+
    +
  • Don't use ViewState for large objects — Serialization overhead grows with data size
    • +
  • Don't store non-serializable objects — ViewState uses JSON serialization
    • +
  • Don't rely on ViewState in ServerInteractive after navigation — ViewState is per-component-instance
    • +
  • Don't mix Web Forms Page-level ViewState with component ViewState — They are separate
    • +
  • Don't assume ViewState survives component disposal — Values are lost when component unmounts
    • +
+
+

Rendering Modes Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AspectSSR (StaticSSR)ServerInteractive
HTTP ContextAvailableUnavailable
ViewState StorageProtected hidden fieldComponent memory
ViewState SerializationAutomatic JSON + encryptionIn-memory only
IsPostBack DetectionHttpMethods.IsPost()_hasInitialized flag
Form SubmissionTraditional HTML POSTJavaScript event, no form submission
Use CaseLegacy form migrationInteractive features
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/UtilityFeatures/WebFormsPage/index.html b/site/UtilityFeatures/WebFormsPage/index.html new file mode 100644 index 000000000..ee2b49dcb --- /dev/null +++ b/site/UtilityFeatures/WebFormsPage/index.html @@ -0,0 +1,4972 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + WebFormsPage - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

WebFormsPage

+

The WebFormsPage component is a unified legacy support wrapper that combines naming container and theming support into a single component. It mirrors System.Web.UI.Page — the root class of every Web Forms page — which established the naming scope for all child controls and applied the page-level theme.

+

Place WebFormsPage in your layout to give all pages automatic ID mangling (naming container) and theme/skin support without per-page configuration.

+

Background

+

In ASP.NET Web Forms, the Page class provided several structural services to all controls on the page:

+
    +
  1. Naming Container — The page was the root INamingContainer, generating fully-qualified client IDs like ctl00_MainContent_MyButton
    2. +
  2. Theme Application — The <%@ Page Theme="..." %> directive applied skin files to all controls
    3. +
  3. ViewState — The page serialized control state to a hidden field (not replicated — Blazor preserves state in component fields)
    4. +
+

WebFormsPage combines the first two capabilities into a single Blazor component.

+

Features Supported in Blazor

+
    +
  • Naming Container — Cascades naming scope to child components, prefixing IDs with the container's ID
    • +
  • UseCtl00Prefix — Optionally prepends ctl00 to the naming hierarchy for full Web Forms ID compatibility
    • +
  • Theme Cascading — Passes a ThemeConfiguration to all child styled components via CascadingValue
    • +
  • Visible — Controls whether child content renders (inherited from BaseWebFormsComponent)
    • +
+

Blazor Notes

+

WebFormsPage inherits from NamingContainer and composes ThemeProvider behavior. Both standalone components remain available for use independently when you only need one capability.

+

Usage

+ +

Place WebFormsPage in your MainLayout.razor wrapping @Body:

+
@inherits LayoutComponentBase
+
+<WebFormsPage ID="MainContent" UseCtl00Prefix="true" Theme="@_theme">
+    @Body
+</WebFormsPage>
+
+@code {
+    private ThemeConfiguration _theme = new();
+}
+
+

This mirrors how <form runat="server"> wrapped all page content in Web Forms. Every page automatically gets naming scope and theming.

+

Per-Page Usage

+

For area-specific configuration (e.g., different themes per section):

+
@page "/admin"
+
+<WebFormsPage ID="AdminContent" Theme="@_adminTheme">
+    <GridView DataSource="@data" AutoGenerateColumns="true" />
+</WebFormsPage>
+
+@code {
+    private ThemeConfiguration _adminTheme = new();
+}
+
+

Naming Only (No Theme)

+

When you only need ID mangling, omit the Theme parameter:

+
<WebFormsPage ID="MainContent" UseCtl00Prefix="true">
+    <Button ID="Submit" Text="Save" />
+    @* Button gets id="ctl00_MainContent_Submit" *@
+</WebFormsPage>
+
+

With Theme Configuration

+
@using BlazorWebFormsComponents.Theming
+
+<WebFormsPage ID="MainContent" Theme="@_theme">
+    <Label Text="Themed label" />
+    <Button ID="Save" Text="Save" />
+</WebFormsPage>
+
+@code {
+    private ThemeConfiguration _theme;
+
+    protected override void OnInitialized()
+    {
+        _theme = new ThemeConfiguration();
+        _theme.AddSkin("Label", new ControlSkin { BackColor = WebColor.LightBlue });
+        _theme.AddSkin("Button", new ControlSkin { BackColor = WebColor.Green, ForeColor = WebColor.White });
+    }
+}
+
+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDefaultDescription
IDstringnullSets the naming scope prefix for child component IDs
UseCtl00PrefixboolfalseWhen true, prepends ctl00 to the naming hierarchy
ThemeThemeConfigurationnullTheme configuration to cascade to child components
VisiblebooltrueControls whether child content renders
ChildContentRenderFragment—The page content
+

Relationship to Other Components

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentPurposeWhen to Use
WebFormsPageCombined naming + themingLayout-level wrapper for full legacy support
NamingContainerNaming scope onlyWhen you need nested naming scopes within a page
ThemeProviderTheme cascading onlyWhen demonstrating theming in isolation
+

IsPostBack Property

+

The WebFormsPageBase class provides an IsPostBack property for Web Forms compatibility:

+
public bool IsPostBack => false;  // Always false in page context
+
+
+

Important: IsPostBack always returns false at the page level because Blazor pages don't have HTTP postback semantics. For component-level postback detection (in SSR or interactive modes), use IsPostBack on BaseWebFormsComponent instead.

+
+

For page-level initialization patterns, use the Blazor lifecycle directly:

+
@inherits WebFormsPageBase
+
+@code {
+    protected override void OnInitialized()
+    {
+        // Replaces if (!IsPostBack) pattern
+        LoadInitialData();
+    }
+}
+
+

Moving On

+

As you refactor away from Web Forms patterns:

+
    +
  1. ID Mangling — Consider using Blazor's built-in @ref instead of string-based IDs for element references
    2. +
  2. Theming — Consider migrating to CSS custom properties or a CSS framework for theming
    3. +
  3. ViewState — Blazor preserves component state automatically in component fields; no hidden field serialization needed
    4. +
  4. Form Patterns — For forms that need postback-like behavior in SSR, use ViewState and IsPostBack on components (see ViewStateAndPostBack.md)
    5. +
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/BaseCompareValidator/index.html b/site/ValidationControls/BaseCompareValidator/index.html new file mode 100644 index 000000000..c5ad07bab --- /dev/null +++ b/site/ValidationControls/BaseCompareValidator/index.html @@ -0,0 +1,5002 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BaseCompareValidator - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

BaseCompareValidator

+

The BaseCompareValidator component is an abstract base class that extends BaseValidator with type conversion and comparison logic. It provides the core functionality for validators that need to compare values, such as CompareValidator and RangeValidator.

+

BaseCompareValidator is not used directly in markup. Instead, use its concrete implementations:

+
    +
  • CompareValidator — compares a field value to a constant or another field
    • +
  • RangeValidator — validates that a value falls within a range
    • +
+

Overview

+

BaseCompareValidator adds type conversion and comparison capabilities to the BaseValidator framework. It enables validators to safely compare values of different types (integers, dates, currency, etc.) by converting them to a common type before comparison.

+

Properties

+

Type

+

Specifies the data type for conversion and comparison. All values are converted to this type before comparison occurs.

+
<CompareValidator Type="ValidationDataType.Integer" />
+<RangeValidator Type="ValidationDataType.Date" />
+
+

Supported types:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescriptionExample
StringText comparison (default)"apple", "banana"
IntegerWhole number comparison42, 100, -5
DoubleDecimal number comparison3.14, 99.99
DateDate comparison"2024-01-15"
CurrencyCurrency value comparison19.99, 100.00
+

CultureInvariantValues

+

Controls whether values are converted using culture-invariant or culture-aware parsing.

+
    +
  • true — Values are parsed using invariant culture (e.g., always use "." as decimal separator)
    • +
  • false (default) — Values are parsed using the current UI culture (e.g., "," in many European locales)
    • +
+
<CompareValidator Type="ValidationDataType.Double" 
+                  CultureInvariantValues="true"
+                  ValueToCompare="3.14" />
+
+

This is useful when comparing numeric or currency values across different locales.

+

Type Conversion

+

BaseCompareValidator provides the Compare() method to safely convert and compare values:

+
protected bool Compare(string leftText, 
+                      bool cultureInvariantLeftText, 
+                      string rightText, 
+                      bool cultureInvariantRightText, 
+                      ValidationCompareOperator op, 
+                      ValidationDataType type)
+
+

The comparison logic:

+
    +
  1. Convert Left Value — Converts the field value to the specified type
    2. +
  2. Check Operator — If operator is DataTypeCheck, validation passes (value is valid type)
    3. +
  3. Convert Right Value — Converts the comparison value to the specified type
    4. +
  4. Compare — Performs the comparison and returns the result
    5. +
+

If either value cannot be converted to the specified type, validation fails (except for DataTypeCheck, which only validates the type itself).

+

Examples

+

Integer Comparison

+
<EditForm Model="@model">
+    <InputNumber @bind-Value="model.Age" />
+    <RangeValidator TValue="int"
+                    Type="ValidationDataType.Integer"
+                    MinimumValue="18"
+                    MaximumValue="120"
+                    ErrorMessage="Age must be between 18 and 120" />
+</EditForm>
+
+@code {
+    class FormModel { public int Age { get; set; } }
+    var model = new FormModel();
+}
+
+

Date Comparison

+
<EditForm Model="@model">
+    <InputDate @bind-Value="model.BirthDate" />
+    <RangeValidator TValue="DateTime"
+                    Type="ValidationDataType.Date"
+                    MinimumValue="1900-01-01"
+                    MaximumValue="2023-12-31"
+                    ErrorMessage="Birth date must be between 1900 and 2023" />
+</EditForm>
+
+

Currency Comparison

+
<EditForm Model="@model">
+    <InputNumber @bind-Value="model.Price" />
+    <CompareValidator TValue="decimal"
+                      Type="ValidationDataType.Currency"
+                      ValueToCompare="100.00"
+                      Operator="ValidationCompareOperator.GreaterThanEqual"
+                      ErrorMessage="Price must be at least $100.00" />
+</EditForm>
+
+

Culture-Invariant Parsing

+
<CompareValidator Type="ValidationDataType.Double"
+                  CultureInvariantValues="true"
+                  ValueToCompare="3.14"
+                  ErrorMessage="Must be greater than 3.14" />
+
+

In a German locale, the UI shows "3,14" but validation parses both sides as "3.14" (US format) due to CultureInvariantValues="true".

+

Syntax Comparison

+
+
+
+
<asp:RangeValidator
+    ControlToValidate="AgeInput"
+    Type="Integer"
+    MinimumValue="18"
+    MaximumValue="120"
+    ErrorMessage="Age must be between 18 and 120"
+    Text="Invalid age"
+    runat="server" />
+
+
+
+
<RangeValidator TValue="int"
+    ControlToValidate="Age"
+    Type="ValidationDataType.Integer"
+    MinimumValue="18"
+    MaximumValue="120"
+    ErrorMessage="Age must be between 18 and 120"
+    Text="Invalid age" />
+
+
+
+
+

Key Differences:

+
    +
  • Type uses the ValidationDataType enum instead of string values
    • +
  • Generic type parameter TValue is required in Blazor
    • +
  • No runat="server" needed
    • +
  • Culture-aware vs. culture-invariant parsing is more explicit with CultureInvariantValues
    • +
+

Child Validators

+

BaseCompareValidator has the following concrete implementations:

+
    +
  • CompareValidator — compares a field value to a constant or another field
    • +
  • RangeValidator — validates that a value falls within a minimum and maximum range
    • +
+

See the individual validator pages for specific usage examples and property details.

+

Inherited Properties

+

BaseCompareValidator inherits all properties from BaseValidator:

+
    +
  • ControlToValidate — reference to the input control
    • +
  • ControlRef — Blazor ForwardRef to input control
    • +
  • Display — how error message is displayed
    • +
  • Text — inline error message
    • +
  • ErrorMessage — summary error message
    • +
  • ValidationGroup — selective validation group
    • +
  • Enabled — enable/disable the validator
    • +
  • Style properties (ForeColor, BackColor, CssClass, etc.)
    • +
+

See the BaseValidator page for details on these inherited properties.

+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/BaseValidator/index.html b/site/ValidationControls/BaseValidator/index.html new file mode 100644 index 000000000..5a64bcc8f --- /dev/null +++ b/site/ValidationControls/BaseValidator/index.html @@ -0,0 +1,5006 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BaseValidator - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

BaseValidator

+

The BaseValidator component serves as the abstract base class for all validation controls in BlazorWebFormsComponents. It provides the shared properties, lifecycle, and integration with Blazor's EditForm validation system that all validator components inherit.

+

Original Microsoft documentation for ASP.NET BaseValidator: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.basevalidator?view=netframework-4.8

+

Overview

+

BaseValidator is not used directly in markup—instead, you use its concrete implementations:

+
    +
  • RequiredFieldValidator — validates that a field has a value
    • +
  • CompareValidator — compares a field value to a constant or another field
    • +
  • RangeValidator — validates that a value falls within a range
    • +
  • RegularExpressionValidator — validates against a pattern
    • +
  • CustomValidator — calls a custom validation function
    • +
+

All validators inherit the same set of properties, display modes, and validation group support from BaseValidator.

+

Properties

+

ControlToValidate

+

Reference to the input control to validate. You can specify this in two ways:

+
    +
  1. +

    String ID (Web Forms style): + 

    <InputText @bind-Value="model.Name" />
+<RequiredFieldValidator ControlToValidate="Name" Text="Name is required" />
+
    + The string matches the property name on your EditForm model.

    +
    2. +
  2. +

    ForwardRef (Blazor native): + 

    <InputText @ref="NameInput.Current" @bind-Value="model.Name" />
+<RequiredFieldValidator ControlRef="@NameInput" Text="Name is required" />
+
+@code {
+    ForwardRef<InputBase<string>> NameInput = new ForwardRef<InputBase<string>>();
+}
+
    + When both ControlToValidate and ControlRef are set, ControlRef takes precedence.

    +
    3. +
+

Display

+

Controls how the error message is displayed:

+ + + + + + + + + + + + + + + + + + + + + +
ValueBehavior
Static (default)Error message always takes up space (visibility: hidden when valid)
DynamicError message only appears when invalid (display: none when valid)
NoneError message never displayed
+
<RequiredFieldValidator Display="ValidatorDisplay.Dynamic" Text="Name is required" />
+
+

Text

+

The error message displayed inline next to the validator. Shown when validation fails.

+
<RequiredFieldValidator Text="This field is required" />
+
+

ErrorMessage

+

The error message displayed in the ValidationSummary component. Can be different from Text.

+
<RequiredFieldValidator ErrorMessage="Name field is required" />
+
+

ValidationGroup

+

Groups validators for selective validation. When a button with a matching ValidationGroup is clicked, only validators in that group validate. Requires wrapping your form in <ValidationGroupProvider>.

+
<ValidationGroupProvider>
+    <EditForm Model="@model">
+        <InputText @ref="NameInput.Current" @bind-Value="model.Name" />
+        <RequiredFieldValidator ControlRef="@NameInput" 
+                                Text="Name is required" 
+                                ValidationGroup="Personal" />
+    </EditForm>
+</ValidationGroupProvider>
+
+

Enabled

+

Enable or disable the validator. When disabled, the validator does not perform validation.

+
<RequiredFieldValidator Enabled="@isEnabled" Text="Name is required" />
+
+

Style Properties

+

BaseValidator inherits from BaseStyledComponent and supports all standard Web Forms styling:

+
    +
  • ForeColor — text color of the error message
    • +
  • BackColor — background color
    • +
  • CssClass — CSS class name(s)
    • +
  • Font.Bold, Font.Italic, Font.Name, Font.Size, Font.Strikeout, Font.Underline — font styling
    • +
+
<RequiredFieldValidator ForeColor="Red" CssClass="validation-error" Text="Required" />
+
+

IsValid

+

A read-only property that indicates whether the field is currently valid. Useful for conditionally rendering UI based on validation state.

+
@if (!myValidator.IsValid)
+{
+    <p>Please fix the validation errors above.</p>
+}
+
+@code {
+    RequiredFieldValidator myValidator;
+}
+
+

Validation Lifecycle

+

BaseValidator integrates with Blazor's EditForm validation system:

+
    +
  1. Registration — When a validator initializes, it registers with the cascading EditContext
    2. +
  2. Validation Request — When the form validates (e.g., button submit), the EditContext fires OnValidationRequested
    3. +
  3. Value Resolution — The validator retrieves the current value from the input control
    4. +
  4. Validation — The validator checks the value and updates the message store
    5. +
  5. State Notification — The EditContext is notified of validation state changes
    6. +
  6. Cleanup — When the validator is disposed, it unregisters from the EditContext
    7. +
+

EditContext Integration

+

All validators require a cascading EditContext, typically provided by the EditForm component:

+
<EditForm Model="@model">
+    <InputText @bind-Value="model.Name" />
+    <RequiredFieldValidator Text="Name is required" />
+</EditForm>
+
+

The EditContext coordinates validation across all validators on the form.

+

Syntax Comparison

+
+
+
+
<asp:RequiredFieldValidator
+    ControlToValidate="NameInput"
+    Display="Dynamic"
+    ErrorMessage="Name is required"
+    Text="Name is required"
+    ForeColor="Red"
+    ValidationGroup="Personal"
+    runat="server" />
+
+
+
+
<RequiredFieldValidator
+    ControlToValidate="Name"
+    Display="ValidatorDisplay.Dynamic"
+    ErrorMessage="Name is required"
+    Text="Name is required"
+    ForeColor="Red"
+    ValidationGroup="Personal" />
+
+
+
+
+

Key Differences:

+
    +
  • ControlToValidate in Blazor uses the model property name instead of a control ID
    • +
  • Display uses the ValidatorDisplay enum instead of string values
    • +
  • No runat="server" needed
    • +
  • Optional ControlRef parameter for Blazor-native ForwardRef approach
    • +
  • Removed: EnableClientScript, SetFocusOnError (Web Forms client-side scripting features not needed in Blazor)
    • +
+

Child Validators

+

BaseValidator has the following concrete implementations:

+
    +
  • RequiredFieldValidator — validates that a field has a value
    • +
  • CompareValidator — compares a field value to a constant or another field
    • +
  • RangeValidator — validates that a value falls within a range
    • +
  • RegularExpressionValidator — validates against a pattern
    • +
  • CustomValidator — calls a custom validation function
    • +
+

See the individual validator pages for specific usage examples.

+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/CompareValidator/index.html b/site/ValidationControls/CompareValidator/index.html new file mode 100644 index 000000000..138ce68d4 --- /dev/null +++ b/site/ValidationControls/CompareValidator/index.html @@ -0,0 +1,4909 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CompareValidator - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

CompareValidator

+

The CompareValidator component validates user input by comparing it to a constant value or to the value of another control using a comparison operator (equals, greater than, less than, etc.). Original Web Forms documentation is at: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.comparevalidator?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • Comparison operators: Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan, LessThanEqual, DataTypeCheck
    • +
  • Data type validation: String, Integer, Double, Date, Currency
    • +
  • ValueToCompare property for comparing against a constant value
    • +
  • CultureInvariantValues for culture-independent comparisons
    • +
  • ErrorMessage display when validation fails
    • +
  • Integration with EditForm validation
    • +
+

Web Forms Features NOT Supported

+
    +
  • ControlToCompare is not directly supported; use ValueToCompare with binding instead
    • +
  • Display property (Static, Dynamic, None) - Blazor handles rendering differently
    • +
  • SetFocusOnError - Blazor has different focus management
    • +
+

Syntax Comparison

+
+
+
+
<asp:CompareValidator
+    ControlToCompare="string"
+    ControlToValidate="string"
+    CultureInvariantValues="True|False"
+    Display="None|Static|Dynamic"
+    EnableClientScript="True|False"
+    Enabled="True|False"
+    ErrorMessage="string"
+    ForeColor="color name|#dddddd"
+    ID="string"
+    Operator="Equal|NotEqual|GreaterThan|GreaterThanEqual|LessThan|
+        LessThanEqual|DataTypeCheck"
+    runat="server"
+    SetFocusOnError="True|False"
+    Text="string"
+    Type="String|Integer|Double|Date|Currency"
+    ValidationGroup="string"
+    ValueToCompare="string"
+    Visible="True|False"
+/>
+
+
+
+
<CompareValidator TValue="string"
+    ValueToCompare="100"
+    Operator="ValidationCompareOperator.GreaterThan"
+    Type="ValidationDataType.Integer"
+    ErrorMessage="Value must be greater than 100" />
+
+
+
+
+

Usage Notes

+

The CompareValidator is a generic component that takes a type parameter TValue. It inherits from BaseCompareValidator which provides the core comparison logic.

+

Example: Comparing to a Constant Value

+
<EditForm Model="@model">
+    <InputNumber @bind-Value="model.Age" />
+    <CompareValidator TValue="int"
+        ValueToCompare="18"
+        Operator="ValidationCompareOperator.GreaterThanEqual"
+        Type="ValidationDataType.Integer"
+        ErrorMessage="You must be at least 18 years old" />
+</EditForm>
+
+

Supported Operators

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorDescription
EqualValues must be equal
NotEqualValues must not be equal
GreaterThanInput must be greater than comparison value
GreaterThanEqualInput must be greater than or equal to comparison value
LessThanInput must be less than comparison value
LessThanEqualInput must be less than or equal to comparison value
DataTypeCheckValidates that input can be converted to the specified data type
+

Supported Data Types

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
StringText comparison
IntegerWhole number comparison
DoubleDecimal number comparison
DateDate comparison
CurrencyCurrency value comparison
+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:CompareValidator> to <CompareValidator>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Add generic type parameter — Use TValue="int" or TValue="string" etc.
    4. +
  4. Operator uses enum — Change Operator="GreaterThan" to Operator="ValidationCompareOperator.GreaterThan"
    5. +
  5. Type uses enum — Change Type="Integer" to Type="ValidationDataType.Integer"
    6. +
  6. Remove EnableClientScript — Not applicable in Blazor
    7. +
  7. Remove SetFocusOnError — Not supported in Blazor
    8. +
+

Migration Example

+
+
+
+
<asp:TextBox ID="txtAge" runat="server" />
+<asp:CompareValidator
+    ControlToValidate="txtAge"
+    Operator="GreaterThanEqual"
+    ValueToCompare="18"
+    Type="Integer"
+    ErrorMessage="Must be 18 or older"
+    runat="server" />
+
+
+
+
<InputNumber @bind-Value="model.Age" />
+<CompareValidator TValue="int"
+    ControlToValidate="Age"
+    Operator="ValidationCompareOperator.GreaterThanEqual"
+    ValueToCompare="18"
+    Type="ValidationDataType.Integer"
+    ErrorMessage="Must be 18 or older" />
+
+
+
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/ControlToValidate/index.html b/site/ValidationControls/ControlToValidate/index.html new file mode 100644 index 000000000..09e408b62 --- /dev/null +++ b/site/ValidationControls/ControlToValidate/index.html @@ -0,0 +1,4853 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ControlToValidate - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ControlToValidate - Validator Control References

+

All validator components in BlazorWebFormsComponents support two patterns for referencing the input control to validate: a string-based ID (ControlToValidate) for Web Forms migration, and a typed reference (ControlRef) for Blazor-native development.

+

Original Microsoft implementation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.basevalidator.controltovalidate?view=netframework-4.8

+

Supported Validators

+

This dual-pattern support is available in all validators:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValidatorBase ClassAdditional Parameters
RequiredFieldValidatorBaseValidator<T>—
CompareValidatorBaseCompareValidator<T>Operator, ValueToCompare
RangeValidatorBaseCompareValidator<T>MinimumValue, MaximumValue
RegularExpressionValidatorBaseValidator<string>ValidationExpression, MatchTimeout
CustomValidatorBaseValidator<string>ValidateEmptyText, ServerValidate
+

Pattern 1: ControlToValidate (String ID)

+

The ControlToValidate parameter accepts a string that maps to a property name on the EditContext model. This is the recommended pattern for Web Forms migration because it mirrors the original Web Forms attribute syntax.

+
@using BlazorWebFormsComponents.Validations
+
+<EditForm Model="@model">
+    <InputText @bind-Value="model.Name" />
+    <RequiredFieldValidator ControlToValidate="Name"
+                            Text="Name is required" />
+
+    <InputText @bind-Value="model.Email" />
+    <RegularExpressionValidator ControlToValidate="Email"
+                                 ValidationExpression="^[\w.-]+@[\w.-]+\.\w+$"
+                                 Text="Invalid email format" />
+</EditForm>
+
+@code {
+    private FormModel model = new();
+
+    public class FormModel
+    {
+        public string Name { get; set; } = "";
+        public string Email { get; set; } = "";
+    }
+}
+
+
+

Migration from Web Forms

+

In Web Forms, ControlToValidate referenced a server control ID. +In Blazor, it references the model property name bound to the input field.

+
+

Pattern 2: ControlRef (Blazor-native ForwardRef)

+

The ControlRef parameter accepts a ForwardRef<InputBase<T>>, providing compile-time type safety. Use this pattern in new Blazor code.

+
@using BlazorWebFormsComponents.Validations
+
+<EditForm Model="@model">
+    <InputText @ref="NameInput.Current" @bind-Value="model.Name" />
+    <RequiredFieldValidator ControlRef="@NameInput"
+                            Text="Name is required" />
+
+    <InputNumber @ref="AgeInput.Current" @bind-Value="model.Age" />
+    <RangeValidator ControlRef="@AgeInput"
+                    MinimumValue="1"
+                    MaximumValue="120"
+                    Text="Age must be between 1 and 120" />
+</EditForm>
+
+@code {
+    ForwardRef<InputBase<string>> NameInput = new();
+    ForwardRef<InputBase<int>> AgeInput = new();
+    private FormModel model = new();
+}
+
+

Precedence Rules

+

When both ControlRef and ControlToValidate are provided, ControlRef takes precedence.

+

If neither is set, an InvalidOperationException is thrown at runtime.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ConfigurationBehavior
ControlRef onlyUses typed reference to resolve field and value
ControlToValidate onlyUses string ID to resolve field from EditContext model
Both setControlRef wins
Neither setThrows InvalidOperationException
+

Migrating from ForwardRef to String ID

+

If you are migrating Web Forms markup and want to keep it as close to the original as possible, use the ControlToValidate string pattern:

+
+
+
+
<asp:TextBox ID="txtName" runat="server" />
+<asp:RequiredFieldValidator
+    ControlToValidate="txtName"
+    Text="Name is required"
+    runat="server" />
+
+
+
+
<InputText @bind-Value="model.Name" />
+<RequiredFieldValidator ControlToValidate="Name"
+                        Text="Name is required" />
+
+
+
+
<InputText @ref="NameInput.Current" @bind-Value="model.Name" />
+<RequiredFieldValidator ControlRef="@NameInput"
+                        Text="Name is required" />
+
+
+
+
+
+

Key Difference

+

In Web Forms, ControlToValidate referenced the control's ID. In Blazor, it references the model property name that the input is bound to.

+
+

Complete Example: Registration Form

+
@using BlazorWebFormsComponents.Validations
+
+<ValidationGroupProvider>
+    <EditForm Model="@model">
+        <div>
+            <Label Text="Username:" />
+            <InputText @bind-Value="model.Username" />
+            <RequiredFieldValidator ControlToValidate="Username"
+                                    Text="* Required"
+                                    ValidationGroup="Registration" />
+        </div>
+
+        <div>
+            <Label Text="Email:" />
+            <InputText @bind-Value="model.Email" />
+            <RequiredFieldValidator ControlToValidate="Email"
+                                    Text="* Required"
+                                    ValidationGroup="Registration" />
+            <RegularExpressionValidator ControlToValidate="Email"
+                                         ValidationExpression="^[\w.-]+@[\w.-]+\.\w+$"
+                                         Text="Invalid email"
+                                         ValidationGroup="Registration" />
+        </div>
+
+        <div>
+            <Label Text="Age:" />
+            <InputNumber @bind-Value="model.Age" />
+            <RangeValidator ControlToValidate="Age"
+                            MinimumValue="13"
+                            MaximumValue="120"
+                            Text="Must be 13-120"
+                            ValidationGroup="Registration" />
+        </div>
+
+        <Button Text="Register" ValidationGroup="Registration" />
+        <ValidationSummary ValidationGroup="Registration" />
+    </EditForm>
+</ValidationGroupProvider>
+
+@code {
+    private RegistrationModel model = new();
+
+    public class RegistrationModel
+    {
+        public string Username { get; set; } = "";
+        public string Email { get; set; } = "";
+        public int Age { get; set; }
+    }
+}
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/CustomValidator/index.html b/site/ValidationControls/CustomValidator/index.html new file mode 100644 index 000000000..68568a096 --- /dev/null +++ b/site/ValidationControls/CustomValidator/index.html @@ -0,0 +1,4959 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CustomValidator - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

CustomValidator

+

The CustomValidator component provides custom validation logic using a server-side function. It emulates the ASP.NET Web Forms asp:CustomValidator control, allowing you to define arbitrary validation rules.

+

Original Web Forms documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.customvalidator?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • ServerValidate - Func<string, bool> parameter that executes custom validation logic
    • +
  • ValidateEmptyText - Controls whether empty values are validated
    • +
  • ControlRef - Reference to the input control being validated
    • +
  • Text / ErrorMessage - Inline and summary error messages
    • +
  • ClientValidationFunction - Migration stub (accepted but not executed in Blazor)
    • +
  • IsValid - Indicates whether validation passes
    • +
+

Web Forms Features NOT Supported

+
    +
  • ClientValidationFunction execution - Blazor does not execute client-side JavaScript validation functions. The property is accepted for migration compatibility.
    • +
  • ValidateOnLoad - Not supported
    • +
+

Syntax Comparison

+
+
+
+
<asp:CustomValidator
+    ID="CustomValidator1"
+    runat="server"
+    ControlToValidate="TextBox1"
+    ClientValidationFunction="validateLength"
+    ErrorMessage="Value must be at least 5 characters."
+    OnServerValidate="CustomValidator1_ServerValidate" />
+
+
+
+
@using BlazorWebFormsComponents.Validations
+
+<EditForm Model="@model">
+    <InputText @ref="Input.Current" @bind-Value="model.Value" />
+    <CustomValidator ServerValidate="@ValidateLength"
+                     ControlRef="@Input"
+                     Text="Must be at least 5 characters."
+                     ErrorMessage="Value too short!" />
+</EditForm>
+
+@code {
+    ForwardRef<InputBase<string>> Input = new();
+
+    private bool ValidateLength(string value)
+    {
+        return !string.IsNullOrEmpty(value) && value.Length >= 5;
+    }
+}
+
+
+
+
+

Examples

+

Basic Custom Validation

+
@using BlazorWebFormsComponents.Validations
+
+<EditForm Model="@model" OnValidSubmit="HandleSubmit">
+    <label>Enter a value starting with 'A':</label>
+    <InputText @ref="NameRef.Current" @bind-Value="model.Name" />
+    <CustomValidator ServerValidate="@StartsWithA"
+                     ControlRef="@NameRef"
+                     Text="Must start with 'A'."
+                     ErrorMessage="Value must start with 'A'!" />
+    <button type="submit">Submit</button>
+</EditForm>
+
+@code {
+    ForwardRef<InputBase<string>> NameRef = new();
+    private MyModel model = new();
+
+    private bool StartsWithA(string value)
+        => value.StartsWith("A", StringComparison.OrdinalIgnoreCase);
+
+    private void HandleSubmit() { }
+    public class MyModel { public string Name { get; set; } }
+}
+
+

With ClientValidationFunction (Migration Stub)

+
@* ClientValidationFunction is accepted for migration but not executed in Blazor *@
+<CustomValidator ServerValidate="@AlwaysValid"
+                 ControlRef="@InputRef"
+                 ClientValidationFunction="validateOnClient"
+                 IsValid="true"
+                 Text="Validation failed." />
+
+@code {
+    private bool AlwaysValid(string value) => true;
+}
+
+

ValidateEmptyText

+
@* By default, empty values pass validation. Set ValidateEmptyText to validate them. *@
+<CustomValidator ServerValidate="@RequireValue"
+                 ControlRef="@InputRef"
+                 ValidateEmptyText="true"
+                 Text="A value is required." />
+
+@code {
+    private bool RequireValue(string value) => !string.IsNullOrWhiteSpace(value);
+}
+
+

Key Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
ServerValidateFunc<string, bool>nullCustom validation function
ValidateEmptyTextboolfalseWhether to validate empty/null values
ClientValidationFunctionstringnullMigration stub — name of client-side function (not executed)
IsValidbooltrueWhether the control currently passes validation
ControlRefForwardRef<InputBase<T>>nullReference to the input control being validated
TextstringnullError text displayed inline
ErrorMessagestringnullError text shown in ValidationSummary
+

Migration Notes

+
    +
  1. Remove asp: prefix and runat="server"
    2. +
  2. Replace OnServerValidate="Handler" with ServerValidate="@Handler" — change from event to Func<string, bool>
    3. +
  3. Replace ControlToValidate="TextBox1" with ControlRef="@ref" using ForwardRef
    4. +
  4. ClientValidationFunction is accepted but has no effect in Blazor
    5. +
  5. IsValid defaults to true — use it to programmatically indicate validation state
    6. +
+

Migration Example

+
+
+
+
<asp:TextBox ID="txtValue" runat="server" />
+<asp:CustomValidator
+    ControlToValidate="txtValue"
+    OnServerValidate="Validate_ServerValidate"
+    ClientValidationFunction="validateOnClient"
+    ErrorMessage="Validation failed"
+    Text="Invalid"
+    runat="server" />
+
+
+
+
<InputText @ref="InputRef.Current" @bind-Value="model.Value" />
+<CustomValidator ServerValidate="@ValidateValue"
+                 ControlRef="@InputRef"
+                 Text="Invalid"
+                 ErrorMessage="Validation failed" />
+
+@code {
+    ForwardRef<InputBase<string>> InputRef = new();
+
+    private bool ValidateValue(string value)
+    {
+        return !string.IsNullOrEmpty(value) && value.Length >= 3;
+    }
+}
+
+
+
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/ModelErrorMessage/index.html b/site/ValidationControls/ModelErrorMessage/index.html new file mode 100644 index 000000000..4fabbb925 --- /dev/null +++ b/site/ValidationControls/ModelErrorMessage/index.html @@ -0,0 +1,4864 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ModelErrorMessage - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ModelErrorMessage

+

The ModelErrorMessage component displays model state error messages for a specific key, matching the ASP.NET Web Forms <asp:ModelErrorMessage> control. It renders a <span> containing the error text when errors exist for the given key, and nothing when there are no errors.

+

Original Microsoft documentation for the ASP.NET ModelErrorMessage control is at: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.modelerrormessage?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • ModelStateKey — The key in the model state / EditContext to display errors for
    • +
  • AssociatedControlID — The ID of the associated input control, used with SetFocusOnError
    • +
  • SetFocusOnError — When true, focuses the associated control when an error is displayed
    • +
  • CssClass — CSS class applied to the rendered <span>
    • +
  • Style — Inline style applied to the rendered <span>
    • +
  • ToolTip — Title attribute on the rendered <span>
    • +
  • Enabled — Enable or disable the component
    • +
  • Visible — Show or hide the component
    • +
+

Web Forms Features NOT Supported

+
    +
  • IsValid / Validate() — ModelErrorMessage is a display-only control; validation logic is handled by the EditContext
    • +
  • HeaderText / HeaderStyle — Not part of the original ModelErrorMessage control
    • +
+

Syntax Comparison

+
+
+
+
<asp:ModelErrorMessage
+    runat="server"
+    ModelStateKey="string"
+    AssociatedControlID="string"
+    CssClass="string"
+    SetFocusOnError="True|False"
+    ID="string"
+    Visible="True|False"
+/>
+
+
+
+
<ModelErrorMessage
+    ModelStateKey="NewPassword"
+    AssociatedControlID="password"
+    CssClass="text-danger"
+    SetFocusOnError="true" />
+
+
+
+
+

HTML Output

+

When errors exist for the specified ModelStateKey, ModelErrorMessage renders:

+
<span class="text-danger">The error message text</span>
+
+

When there are no errors, nothing is rendered.

+

Usage Notes

+

ModelErrorMessage requires a cascading EditContext — it must be placed inside an <EditForm>. It listens for validation state changes and automatically updates when errors are added or removed.

+

Adding Errors via ValidationMessageStore

+

In Web Forms, model state errors are added in code-behind via ModelState.AddModelError(). In Blazor, the equivalent pattern uses ValidationMessageStore on the EditContext:

+
@using BlazorWebFormsComponents.Validations
+
+<EditForm Model="@model" OnValidSubmit="HandleSubmit">
+    <input id="password" type="password" @bind="model.NewPassword" />
+
+    <ModelErrorMessage
+        ModelStateKey="NewPassword"
+        AssociatedControlID="password"
+        CssClass="text-danger"
+        SetFocusOnError="true" />
+
+    <Button Text="Submit" />
+</EditForm>
+
+@code {
+    private MyModel model = new();
+    private EditContext editContext;
+    private ValidationMessageStore messageStore;
+
+    protected override void OnInitialized()
+    {
+        editContext = new EditContext(model);
+        messageStore = new ValidationMessageStore(editContext);
+    }
+
+    private void HandleSubmit()
+    {
+        messageStore.Clear();
+
+        if (string.IsNullOrEmpty(model.NewPassword))
+        {
+            // Equivalent to ModelState.AddModelError("NewPassword", "...")
+            messageStore.Add(editContext.Field("NewPassword"),
+                "Password is required.");
+            editContext.NotifyValidationStateChanged();
+        }
+    }
+}
+
+

Multiple Errors

+

If multiple errors are added for the same key, they are displayed separated by <br> tags within a single <span>.

+

Migration Notes

+

Migration from Web Forms to Blazor is straightforward:

+
    +
  1. Remove the asp: prefix and runat="server" attribute
    2. +
  2. Wrap the form in an <EditForm> (replacing <form runat="server">)
    3. +
  3. Replace ModelState.AddModelError() calls with ValidationMessageStore.Add()
    4. +
+

Migration Example

+
+
+
+
<asp:ModelErrorMessage runat="server"
+    ModelStateKey="NewPassword"
+    AssociatedControlID="password"
+    CssClass="text-danger"
+    SetFocusOnError="true" />
+
+
+
+
<ModelErrorMessage
+    ModelStateKey="NewPassword"
+    AssociatedControlID="password"
+    CssClass="text-danger"
+    SetFocusOnError="true" />
+
+
+
+
+
+

Code-behind migration

+

The biggest change is in the code-behind: Web Forms uses ModelState.AddModelError(key, message) while Blazor uses ValidationMessageStore.Add(editContext.Field(key), message) followed by editContext.NotifyValidationStateChanged().

+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/RangeValidator/index.html b/site/ValidationControls/RangeValidator/index.html new file mode 100644 index 000000000..e53f25311 --- /dev/null +++ b/site/ValidationControls/RangeValidator/index.html @@ -0,0 +1,4904 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + RangeValidator - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

RangeValidator

+

The RangeValidator component validates that user input falls within a specified range of values. This is useful for ensuring numeric values, dates, or strings are within acceptable bounds. Original Web Forms documentation is at: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.rangevalidator?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • MinimumValue and MaximumValue range boundaries
    • +
  • Data type validation: String, Integer, Double, Date, Currency
    • +
  • CultureInvariantValues for culture-independent comparisons
    • +
  • ErrorMessage display when validation fails
    • +
  • Integration with EditForm validation
    • +
+

Web Forms Features NOT Supported

+
    +
  • Display property (Static, Dynamic, None) - Blazor handles rendering differently
    • +
  • SetFocusOnError - Blazor has different focus management
    • +
  • EnableClientScript - Blazor uses its own validation model
    • +
+

Syntax Comparison

+
+
+
+
<asp:RangeValidator
+    ControlToValidate="string"
+    CultureInvariantValues="True|False"
+    Display="None|Static|Dynamic"
+    EnableClientScript="True|False"
+    Enabled="True|False"
+    ErrorMessage="string"
+    ForeColor="color name|#dddddd"
+    ID="string"
+    MaximumValue="string"
+    MinimumValue="string"
+    runat="server"
+    SetFocusOnError="True|False"
+    Text="string"
+    Type="String|Integer|Double|Date|Currency"
+    ValidationGroup="string"
+    Visible="True|False"
+/>
+
+
+
+
<RangeValidator TValue="string"
+    MinimumValue="1"
+    MaximumValue="100"
+    Type="ValidationDataType.Integer"
+    ErrorMessage="Value must be between 1 and 100" />
+
+
+
+
+

Usage Notes

+

The RangeValidator is a generic component that takes a type parameter TValue. It inherits from BaseCompareValidator which provides the core comparison logic.

+

Example: Validating a Numeric Range

+
<EditForm Model="@model">
+    <InputNumber @bind-Value="model.Quantity" />
+    <RangeValidator TValue="int"
+        MinimumValue="1"
+        MaximumValue="999"
+        Type="ValidationDataType.Integer"
+        ErrorMessage="Quantity must be between 1 and 999" />
+</EditForm>
+
+

Example: Validating a Date Range

+
<EditForm Model="@model">
+    <InputDate @bind-Value="model.BirthDate" />
+    <RangeValidator TValue="DateTime"
+        MinimumValue="1/1/1900"
+        MaximumValue="12/31/2010"
+        Type="ValidationDataType.Date"
+        ErrorMessage="Birth date must be between 1900 and 2010" />
+</EditForm>
+
+

Supported Data Types

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
StringAlphabetical string comparison
IntegerWhole number range validation
DoubleDecimal number range validation
DateDate range validation
CurrencyCurrency value range validation
+

Behavior Notes

+
    +
  • Empty or null values pass validation (use RequiredFieldValidator in combination if the field is required)
    • +
  • Whitespace-only values pass validation
    • +
  • Both MinimumValue and MaximumValue boundaries are inclusive
    • +
+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:RangeValidator> to <RangeValidator>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Add generic type parameter — Use TValue="int" or TValue="DateTime" etc.
    4. +
  4. Type uses enum — Change Type="Integer" to Type="ValidationDataType.Integer"
    5. +
  5. Remove EnableClientScript — Not applicable in Blazor
    6. +
  6. Remove SetFocusOnError — Not supported in Blazor
    7. +
+

Migration Example

+
+
+
+
<asp:TextBox ID="txtQty" runat="server" />
+<asp:RangeValidator
+    ControlToValidate="txtQty"
+    MinimumValue="1"
+    MaximumValue="999"
+    Type="Integer"
+    ErrorMessage="Quantity must be between 1 and 999"
+    runat="server" />
+
+
+
+
<InputNumber @bind-Value="model.Quantity" />
+<RangeValidator TValue="int"
+    ControlToValidate="Quantity"
+    MinimumValue="1"
+    MaximumValue="999"
+    Type="ValidationDataType.Integer"
+    ErrorMessage="Quantity must be between 1 and 999" />
+
+
+
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/RegularExpressionValidator/index.html b/site/ValidationControls/RegularExpressionValidator/index.html new file mode 100644 index 000000000..cb055a7ac --- /dev/null +++ b/site/ValidationControls/RegularExpressionValidator/index.html @@ -0,0 +1,5193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + RegularExpressionValidator - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

RegularExpressionValidator

+

The RegularExpressionValidator component validates that user input matches a specified regular expression pattern. It emulates the ASP.NET Web Forms asp:RegularExpressionValidator control, useful for enforcing formats such as email addresses, phone numbers, postal codes, and other structured input.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.regularexpressionvalidator?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • ValidationExpression — The regular expression pattern to match against
    • +
  • MatchTimeout — Timeout for regex evaluation to prevent ReDoS attacks
    • +
  • ControlToValidate / ControlRef — Reference to the input control to validate
    • +
  • Text — Error message displayed inline when validation fails
    • +
  • ErrorMessage — Message shown in ValidationSummary
    • +
  • ValidationGroup — Group name for selective validation
    • +
  • Display — How the error message is displayed (Static, Dynamic, None)
    • +
  • Enabled — Enable or disable the validator
    • +
  • All style properties (ForeColor, BackColor, CssClass, etc.)
    • +
+

Web Forms Features NOT Supported

+
    +
  • EnableClientScript — Blazor uses its own validation model instead of client-side JavaScript
    • +
  • SetFocusOnError — Blazor has different focus management
    • +
+

Syntax Comparison

+
+
+
+
<asp:RegularExpressionValidator
+    ControlToValidate="string"
+    Display="None|Static|Dynamic"
+    EnableClientScript="True|False"
+    Enabled="True|False"
+    ErrorMessage="string"
+    ForeColor="color name|#dddddd"
+    ID="string"
+    runat="server"
+    SetFocusOnError="True|False"
+    Text="string"
+    ValidationExpression="string"
+    ValidationGroup="string"
+    Visible="True|False"
+/>
+
+
+
+
<RegularExpressionValidator
+    ControlToValidate="PropertyName"
+    ValidationExpression="^[\w.-]+@[\w.-]+\.\w+$"
+    Text="Invalid format"
+    ErrorMessage="The field does not match the required pattern"
+    Display="ValidatorDisplay.Dynamic"
+    ValidationGroup="MyGroup"
+    Enabled="true" />
+
+
+
+
+

Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
ValidationExpressionstringnullRegular expression pattern to validate against
MatchTimeoutint?nullTimeout in milliseconds for regex evaluation (prevents ReDoS)
ControlToValidatestringnullModel property name to validate
ControlRefForwardRef<InputBase<T>>nullTyped reference to input control
TextstringnullError text displayed inline
ErrorMessagestringnullError text shown in ValidationSummary
DisplayValidatorDisplayStaticHow error message is displayed
ValidationGroupstringnullSelective validation group
EnabledbooltrueEnable or disable the validator
ForeColorWebColorRedText color of error message
+

Email Validation

+
<EditForm Model="@model">
+    <InputText @bind-Value="model.Email" />
+    <RegularExpressionValidator
+        ControlToValidate="Email"
+        ValidationExpression="^[\w.-]+@[\w.-]+\.\w+$"
+        Text="Please enter a valid email address"
+        ErrorMessage="Invalid email format" />
+    <button type="submit">Submit</button>
+</EditForm>
+
+@code {
+    private var model = new ContactModel();
+
+    public class ContactModel
+    {
+        public string Email { get; set; } = "";
+    }
+}
+
+

Phone Number Validation

+
<EditForm Model="@model">
+    <InputText @bind-Value="model.Phone" placeholder="(555) 123-4567" />
+    <RegularExpressionValidator
+        ControlToValidate="Phone"
+        ValidationExpression="^(\(\d{3}\)\s?)?\d{3}-\d{4}$"
+        Text="Format: (555) 123-4567"
+        ErrorMessage="Invalid phone number format" />
+</EditForm>
+
+

Postal Code Validation with ForwardRef

+
@using BlazorWebFormsComponents.Validations
+
+<EditForm Model="@model">
+    <InputText @ref="ZipInput.Current" @bind-Value="model.ZipCode" placeholder="12345 or 12345-6789" />
+    <RegularExpressionValidator
+        ControlRef="@ZipInput"
+        ValidationExpression="^\d{5}(-\d{4})?$"
+        Text="Enter a valid ZIP code (e.g., 12345 or 12345-6789)"
+        Display="ValidatorDisplay.Dynamic" />
+</EditForm>
+
+@code {
+    ForwardRef<InputBase<string>> ZipInput = new();
+    private var model = new AddressModel();
+}
+
+

With MatchTimeout (ReDoS Prevention)

+
<RegularExpressionValidator
+    ControlToValidate="Input"
+    ValidationExpression="^(?:[a-z0-9]+\.)*[a-z0-9]+$"
+    MatchTimeout="2000"
+    Text="Invalid format"
+    ErrorMessage="Input does not match the required pattern" />
+
+

Username Validation

+
<EditForm Model="@model">
+    <InputText @bind-Value="model.Username" placeholder="alphanumeric and underscore" />
+    <RegularExpressionValidator
+        ControlToValidate="Username"
+        ValidationExpression="^[a-zA-Z0-9_]{3,20}$"
+        Text="Username must be 3-20 characters (letters, numbers, underscore only)"
+        ErrorMessage="Username format is invalid" />
+</EditForm>
+
+

URL Validation

+
<EditForm Model="@model">
+    <InputText @bind-Value="model.Website" placeholder="https://example.com" />
+    <RegularExpressionValidator
+        ControlToValidate="Website"
+        ValidationExpression="^https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*)$"
+        Text="Please enter a valid URL"
+        ErrorMessage="The website URL is not valid" />
+</EditForm>
+
+

Hexadecimal Color Code Validation

+
<EditForm Model="@model">
+    <InputText @bind-Value="model.Color" placeholder="#RRGGBB" />
+    <RegularExpressionValidator
+        ControlToValidate="Color"
+        ValidationExpression="^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
+        Text="Enter a valid hex color (e.g., #FF5733 or #F57)"
+        ErrorMessage="Invalid color format" />
+</EditForm>
+
+
+

Preventing ReDoS Attacks

+

Use the MatchTimeout property when your regex pattern could be vulnerable to Regular Expression Denial of Service (ReDoS) attacks. This sets a timeout (in milliseconds) for the regex engine, preventing catastrophic backtracking on malicious input. For example, set MatchTimeout="2000" for a 2-second timeout.

+
+

HTML Output

+

Email Input with Validation: +

<!-- Blazor Input -->
+<InputText @bind-Value="model.Email" />
+<RegularExpressionValidator
+    ControlToValidate="Email"
+    ValidationExpression="^[\w.-]+@[\w.-]+\.\w+$"
+    Text="Invalid email"
+    ErrorMessage="Email format is invalid" />
+
+<!-- Rendered HTML (valid input) -->
+<input type="text" value="user@example.com" />
+
+<!-- Rendered HTML (invalid input, Display=Dynamic) -->
+<input type="text" value="invalid-email" />
+<span style="color:Red;">Invalid email</span>
+

+

Common Regular Expression Patterns

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PatternUse CaseExample
^[\w.-]+@[\w.-]+\.\w+$Email addressuser@example.com
^(\(\d{3}\)\s?)?\d{3}-\d{4}$US Phone(555) 123-4567
^\d{5}(-\d{4})?$US ZIP Code12345 or 12345-6789
^[a-zA-Z0-9_]{3,20}$Usernamejohn_doe, user123
^https?://...URLhttps://example.com
^#([A-Fa-f0-9]{6}\|[A-Fa-f0-9]{3})$Hex Color#FF5733 or #F57
^\d{3}-\d{2}-\d{4}$SSN123-45-6789
^\d{4}[-/]\d{2}[-/]\d{2}$Date2023-12-25 or 2023/12/25
+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:RegularExpressionValidator> to <RegularExpressionValidator>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Update ControlToValidate — Use the model property name instead of a control ID, or use ControlRef with ForwardRef
    4. +
  4. Display uses enum — Change Display="Dynamic" to Display="ValidatorDisplay.Dynamic"
    5. +
  5. ValidationExpression stays the same — Regex patterns are identical between Web Forms and Blazor
    6. +
  6. Remove EnableClientScript — Not applicable in Blazor
    7. +
  7. Remove SetFocusOnError — Not supported in Blazor
    8. +
+

Migration Example

+
+
+
+
<asp:TextBox ID="txtEmail" runat="server" />
+<asp:RegularExpressionValidator
+    ControlToValidate="txtEmail"
+    ValidationExpression="^[\w.-]+@[\w.-]+\.\w+$"
+    ErrorMessage="Invalid email"
+    Text="*"
+    Display="Dynamic"
+    runat="server" />
+
+
+
+
<InputText @bind-Value="model.Email" />
+<RegularExpressionValidator
+    ControlToValidate="Email"
+    ValidationExpression="^[\w.-]+@[\w.-]+\.\w+$"
+    ErrorMessage="Invalid email"
+    Text="*"
+    Display="ValidatorDisplay.Dynamic" />
+
+
+
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/RequiredFieldValidator/index.html b/site/ValidationControls/RequiredFieldValidator/index.html new file mode 100644 index 000000000..fad79b1f4 --- /dev/null +++ b/site/ValidationControls/RequiredFieldValidator/index.html @@ -0,0 +1,5067 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + RequiredFieldValidator - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

RequiredFieldValidator

+

The RequiredFieldValidator component validates that another field on the form has a value provided. It emulates the ASP.NET Web Forms asp:RequiredFieldValidator control.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.requiredfieldvalidator?view=netframework-4.8

+

Features Supported in Blazor

+
    +
  • ControlToValidate — Reference to the input control to validate (model property name)
    • +
  • ControlRef — Typed reference using ForwardRef<InputBase<T>>
    • +
  • Text — Error message displayed inline when validation fails
    • +
  • ErrorMessage — Message shown in ValidationSummary
    • +
  • InitialValue — The initial value to treat as "empty" (default: empty string)
    • +
  • ValidationGroup — Group name for selective validation
    • +
  • Display — How the error message is displayed (Static, Dynamic, None)
    • +
  • Enabled — Enable or disable the validator
    • +
  • All style properties (ForeColor, BackColor, CssClass, etc.)
    • +
+

Web Forms Features NOT Supported

+
    +
  • EnableClientScript — Blazor uses its own validation model
    • +
  • SetFocusOnError — Blazor has different focus management
    • +
+

Syntax Comparison

+
+
+
+
<asp:RequiredFieldValidator
+    ControlToValidate="string"
+    Display="None|Static|Dynamic"
+    EnableClientScript="True|False"
+    Enabled="True|False"
+    ErrorMessage="string"
+    ForeColor="color name|#dddddd"
+    ID="string"
+    InitialValue="string"
+    runat="server"
+    SetFocusOnError="True|False"
+    Text="string"
+    ValidationGroup="string"
+    Visible="True|False"
+/>
+
+
+
+
<RequiredFieldValidator
+    ControlToValidate="PropertyName"
+    Text="This field is required"
+    ErrorMessage="Field is required"
+    Display="ValidatorDisplay.Dynamic"
+    ValidationGroup="MyGroup"
+    Enabled="true" />
+
+
+
+
+

Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
ControlToValidatestringnullModel property name to validate
ControlRefForwardRef<InputBase<T>>nullTyped reference to input control
TextstringnullError text displayed inline
ErrorMessagestringnullError text shown in ValidationSummary
InitialValuestring""Value treated as "not entered"
DisplayValidatorDisplayStaticHow error message is displayed
ValidationGroupstringnullSelective validation group
EnabledbooltrueEnable or disable the validator
ForeColorWebColorRedText color of error message
+

Usage Notes

+
    +
  • The validator checks that the input value differs from InitialValue (default: empty string)
    • +
  • Both ControlToValidate (string) and ControlRef (ForwardRef) patterns are supported — see ControlToValidate for details
    • +
  • When ControlRef and ControlToValidate are both set, ControlRef takes precedence
    • +
  • Requires a cascading EditContext — must be placed inside an <EditForm>
    • +
+

ValidationGroup Support

+

The ValidationGroup property allows validators to participate in selective validation. When a button with a matching ValidationGroup is clicked, only validators in that group will validate.

+

Key Points:

+
    +
  1. Validators and buttons with the same ValidationGroup value work together
    2. +
  2. Validators without a ValidationGroup are triggered by buttons without a ValidationGroup
    3. +
  3. Must wrap form in <ValidationGroupProvider> to use ValidationGroup
    4. +
+

Examples

+

Basic Required Field

+
<EditForm Model="@model" OnValidSubmit="HandleSubmit">
+    <InputText @bind-Value="model.Name" />
+    <RequiredFieldValidator ControlToValidate="Name"
+                            Text="Name is required"
+                            ErrorMessage="Please enter your name" />
+    <button type="submit">Submit</button>
+</EditForm>
+
+@code {
+    private var model = new FormModel();
+    private void HandleSubmit() { }
+}
+
+

Using ForwardRef

+
@using BlazorWebFormsComponents.Validations
+
+<EditForm Model="@model">
+    <InputText @ref="NameInput.Current" @bind-Value="model.Name" />
+    <RequiredFieldValidator ControlRef="@NameInput"
+                            Text="Name is required"
+                            Display="ValidatorDisplay.Dynamic" />
+</EditForm>
+
+@code {
+    ForwardRef<InputBase<string>> NameInput = new();
+    private var model = new FormModel();
+}
+
+

With ValidationGroup

+
@using BlazorWebFormsComponents.Validations
+
+<ValidationGroupProvider>
+    <EditForm Model="@model">
+        <InputText @ref="NameInput.Current" @bind-Value="model.Name" />
+        <RequiredFieldValidator ControlToValidate="@NameInput"
+                                Text="Name is required"
+                                ValidationGroup="Personal" />
+
+        <InputText @ref="CompanyInput.Current" @bind-Value="model.Company" />
+        <RequiredFieldValidator ControlToValidate="@CompanyInput"
+                                Text="Company is required"
+                                ValidationGroup="Business" />
+
+        <Button Text="Validate Personal" ValidationGroup="Personal" />
+        <Button Text="Validate Business" ValidationGroup="Business" />
+    </EditForm>
+</ValidationGroupProvider>
+
+@code {
+    ForwardRef<InputBase<string>> NameInput = new();
+    ForwardRef<InputBase<string>> CompanyInput = new();
+    private var model = new FormModel();
+}
+
+

InitialValue

+
@* Validates that the user changed the dropdown from its default value *@
+<InputSelect @bind-Value="model.Country">
+    <option value="">-- Select Country --</option>
+    <option value="US">United States</option>
+    <option value="CA">Canada</option>
+</InputSelect>
+<RequiredFieldValidator ControlToValidate="Country"
+                        InitialValue=""
+                        Text="Please select a country" />
+
+

Migration Notes

+
    +
  1. Remove asp: prefix — Change <asp:RequiredFieldValidator> to <RequiredFieldValidator>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Update ControlToValidate — Use model property name instead of control ID, or use ControlRef with ForwardRef
    4. +
  4. Display uses enum — Change Display="Dynamic" to Display="ValidatorDisplay.Dynamic"
    5. +
  5. Remove EnableClientScript — Not applicable in Blazor
    6. +
  6. Remove SetFocusOnError — Not supported in Blazor
    7. +
  7. InitialValue, Text, ErrorMessage transfer directly — No changes needed
    8. +
+

Migration Example

+
+
+
+
<asp:TextBox ID="txtName" runat="server" />
+<asp:RequiredFieldValidator
+    ControlToValidate="txtName"
+    Text="* Required"
+    ErrorMessage="Name is required"
+    Display="Dynamic"
+    ForeColor="Red"
+    runat="server" />
+
+
+
+
<InputText @bind-Value="model.Name" />
+<RequiredFieldValidator
+    ControlToValidate="Name"
+    Text="* Required"
+    ErrorMessage="Name is required"
+    Display="ValidatorDisplay.Dynamic"
+    ForeColor="WebColor.Red" />
+
+
+
+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/ValidationControls/ValidationSummary/index.html b/site/ValidationControls/ValidationSummary/index.html new file mode 100644 index 000000000..060b90b64 --- /dev/null +++ b/site/ValidationControls/ValidationSummary/index.html @@ -0,0 +1,5323 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ValidationSummary - BlazorWebFormsComponents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+ +
+ + + + + + + + +

ValidationSummary

+

The ValidationSummary component displays a summary of all validation errors on a form. In BlazorWebFormsComponents, this component is named AspNetValidationSummary to avoid conflicts with Blazor's built-in ValidationSummary component. This tag name may change in future versions to align more closely with the original ASP.NET control.

+

Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.validationsummary?view=netframework-4.8

+
+

Component Name

+

Use <AspNetValidationSummary> in Blazor markup. The name differs from the Web Forms <asp:ValidationSummary> to avoid conflicts with Blazor's built-in <ValidationSummary> component.

+
+

Features Supported in Blazor

+
    +
  • DisplayMode — How errors are displayed: BulletList, List, or SingleParagraph
    • +
  • HeaderText — Text displayed above the error list
    • +
  • ShowSummary — Whether to display the summary (default: true)
    • +
  • ValidationGroup — Only show errors from validators in the specified group
    • +
  • CssClass — CSS class applied to the summary container
    • +
  • ForeColor — Text color for error messages
    • +
  • Enabled — Enable or disable the summary
    • +
  • Visible — Show or hide the component
    • +
  • All style properties (BackColor, BorderColor, BorderStyle, BorderWidth, Width, Height, Font)
    • +
+

Web Forms Features NOT Supported

+
    +
  • ShowMessageBox — JavaScript alert boxes are not supported; use inline display instead
    • +
  • EnableClientScript — Blazor uses its own validation model (stub parameter exists for migration compatibility)
    • +
+

Syntax Comparison

+
+
+
+
<asp:ValidationSummary
+    BackColor="color name|#dddddd"
+    BorderColor="color name|#dddddd"
+    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|Inset|Outset"
+    BorderWidth="size"
+    CssClass="string"
+    DisplayMode="BulletList|List|SingleParagraph"
+    EnableClientScript="True|False"
+    Enabled="True|False"
+    Font-Bold="True|False"
+    ForeColor="color name|#dddddd"
+    HeaderText="string"
+    Height="size"
+    ID="string"
+    runat="server"
+    ShowMessageBox="True|False"
+    ShowSummary="True|False"
+    ValidationGroup="string"
+    Visible="True|False"
+    Width="size"
+/>
+
+
+
+
<AspNetValidationSummary
+    BackColor="WebColor.LightYellow"
+    BorderColor="WebColor.Red"
+    BorderStyle="BorderStyle.Solid"
+    CssClass="validation-summary"
+    DisplayMode="ValidationSummaryDisplayMode.BulletList"
+    Enabled="true"
+    ForeColor="WebColor.Red"
+    HeaderText="Please correct the following errors:"
+    ShowSummary="true"
+    ValidationGroup="MyGroup"
+    Visible="true"
+/>
+
+
+
+
+

Properties

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDefaultDescription
DisplayModeValidationSummaryDisplayModeBulletListHow errors are rendered
HeaderTextstringnullText shown above the error list
ShowSummarybooltrueWhether to display the summary
ValidationGroupstringnullFilter errors by validation group
CssClassstringnullCSS class for the container
ForeColorWebColordefaultText color of error messages
BackColorWebColordefaultBackground color
BorderColorWebColordefaultBorder color
BorderStyleBorderStyleNotSetBorder style
BorderWidthUnitdefaultBorder width
WidthUnitdefaultContainer width
HeightUnitdefaultContainer height
FontFontInfonew FontInfo()Font properties (Bold, Italic, etc.)
EnabledbooltrueEnable or disable the component
VisiblebooltrueShow or hide the component
EnableClientScriptbooltrueStub for migration compatibility (no effect)
ShowMessageBoxboolfalseStub for migration compatibility (no effect)
+

DisplayMode Values

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescriptionRendered As
BulletListBulleted list of errors (default)<ul><li>...</li></ul>
ListPlain list of errorsLine-break separated text
SingleParagraphAll errors in one paragraphSpace-separated text
+

Examples

+

Basic Validation Summary

+
<EditForm Model="@model" OnValidSubmit="HandleSubmit">
+    <InputText @bind-Value="model.Name" />
+    <RequiredFieldValidator ControlToValidate="Name"
+                            Text="*"
+                            ErrorMessage="Name is required" />
+
+    <InputText @bind-Value="model.Email" />
+    <RequiredFieldValidator ControlToValidate="Email"
+                            Text="*"
+                            ErrorMessage="Email is required" />
+
+    <AspNetValidationSummary HeaderText="Please fix the following errors:" />
+    <button type="submit">Submit</button>
+</EditForm>
+
+@code {
+    private var model = new FormModel();
+
+    private void HandleSubmit()
+    {
+        // Process form submission
+    }
+}
+
+

With ValidationGroup

+
@using BlazorWebFormsComponents.Validations
+
+<ValidationGroupProvider>
+    <EditForm Model="@model">
+        <InputText @bind-Value="model.Name" />
+        <RequiredFieldValidator ControlToValidate="Name"
+                                Text="*"
+                                ErrorMessage="Name is required"
+                                ValidationGroup="Personal" />
+
+        <AspNetValidationSummary
+            HeaderText="Personal Info Errors:"
+            ValidationGroup="Personal"
+            DisplayMode="ValidationSummaryDisplayMode.BulletList" />
+
+        <Button Text="Validate" ValidationGroup="Personal" />
+    </EditForm>
+</ValidationGroupProvider>
+
+@code {
+    private var model = new FormModel();
+}
+
+

Display Modes

+
@* Bulleted list (default) *@
+<AspNetValidationSummary 
+    HeaderText="Errors:"
+    DisplayMode="ValidationSummaryDisplayMode.BulletList" />
+
+@* Plain list *@
+<AspNetValidationSummary 
+    HeaderText="Errors:"
+    DisplayMode="ValidationSummaryDisplayMode.List" />
+
+@* Single paragraph *@
+<AspNetValidationSummary 
+    HeaderText="Errors:"
+    DisplayMode="ValidationSummaryDisplayMode.SingleParagraph" />
+
+

Styled Summary

+
<AspNetValidationSummary
+    HeaderText="Errors occurred:"
+    CssClass="alert alert-danger"
+    ForeColor="WebColor.DarkRed"
+    BackColor="WebColor.LightPink"
+    BorderColor="WebColor.Red"
+    BorderStyle="BorderStyle.Solid"
+    BorderWidth="1px"
+    DisplayMode="ValidationSummaryDisplayMode.BulletList" />
+
+

Multiple Validation Groups

+
@using BlazorWebFormsComponents.Validations
+
+<ValidationGroupProvider>
+    <EditForm Model="@model" OnValidSubmit="HandleSubmit">
+        @* Personal Information Section *@
+        <h3>Personal Information</h3>
+        <InputText @bind-Value="model.FirstName" />
+        <RequiredFieldValidator ControlToValidate="FirstName"
+                                ErrorMessage="First name is required"
+                                ValidationGroup="Personal" />
+
+        <InputText @bind-Value="model.LastName" />
+        <RequiredFieldValidator ControlToValidate="LastName"
+                                ErrorMessage="Last name is required"
+                                ValidationGroup="Personal" />
+
+        <AspNetValidationSummary
+            HeaderText="Personal Info Errors:"
+            ValidationGroup="Personal"
+            CssClass="alert alert-danger" />
+
+        @* Business Information Section *@
+        <h3>Business Information</h3>
+        <InputText @bind-Value="model.Company" />
+        <RequiredFieldValidator ControlToValidate="Company"
+                                ErrorMessage="Company is required"
+                                ValidationGroup="Business" />
+
+        <InputText @bind-Value="model.JobTitle" />
+        <RequiredFieldValidator ControlToValidate="JobTitle"
+                                ErrorMessage="Job title is required"
+                                ValidationGroup="Business" />
+
+        <AspNetValidationSummary
+            HeaderText="Business Info Errors:"
+            ValidationGroup="Business"
+            CssClass="alert alert-danger" />
+
+        <Button Text="Validate Personal" ValidationGroup="Personal" />
+        <Button Text="Validate Business" ValidationGroup="Business" />
+        <Button Text="Submit All" CausesValidation="false" OnClick="HandleSubmit" />
+    </EditForm>
+</ValidationGroupProvider>
+
+@code {
+    private var model = new FormModel();
+
+    private void HandleSubmit()
+    {
+        // Process form submission
+    }
+}
+
+

With Multiple Validators

+
<EditForm Model="@model" OnValidSubmit="HandleSubmit">
+    <div>
+        <Label Text="Email:" AssociatedControlID="email" />
+        <InputText id="email" @bind-Value="model.Email" />
+        <RequiredFieldValidator ControlToValidate="Email"
+                                ErrorMessage="Email is required"
+                                Text="*" />
+        <RegularExpressionValidator ControlToValidate="Email"
+                                    ValidationExpression="^[\w.-]+@[\w.-]+\.\w+$"
+                                    ErrorMessage="Email format is invalid"
+                                    Text="Invalid format" />
+    </div>
+
+    <AspNetValidationSummary
+        HeaderText="Please correct the following errors:"
+        DisplayMode="ValidationSummaryDisplayMode.BulletList"
+        CssClass="validation-summary alert alert-danger" />
+
+    <button type="submit">Submit</button>
+</EditForm>
+
+@code {
+    private var model = new FormModel();
+
+    private void HandleSubmit()
+    {
+        // Form is valid and ready to submit
+    }
+}
+
+

HTML Output

+

Bulleted List (default): +

<!-- Blazor Input -->
+<AspNetValidationSummary 
+    HeaderText="Errors:"
+    DisplayMode="ValidationSummaryDisplayMode.BulletList" />
+
+<!-- Rendered HTML (with errors) -->
+<div title="">
+    <b>Errors:</b>
+    <ul>
+        <li>Name is required</li>
+        <li>Email format is invalid</li>
+    </ul>
+</div>
+

+

Plain List: +

<!-- Blazor Input -->
+<AspNetValidationSummary 
+    DisplayMode="ValidationSummaryDisplayMode.List" />
+
+<!-- Rendered HTML -->
+<div title="">
+    Name is required<br>
+    Email format is invalid<br>
+</div>
+

+

Migration Notes

+
    +
  1. Change tag name — Replace <asp:ValidationSummary> with <AspNetValidationSummary>
    2. +
  2. Remove runat="server" — Not needed in Blazor
    3. +
  3. Remove ShowMessageBox — JavaScript alert boxes are not supported in Blazor
    4. +
  4. Remove EnableClientScript — Not applicable in Blazor (though the parameter exists as a stub)
    5. +
  5. Update DisplayMode enum — Change DisplayMode="BulletList" to DisplayMode="ValidationSummaryDisplayMode.BulletList"
    6. +
  6. Colors use WebColor enum — Instead of color name strings
    7. +
  7. Must be inside <EditForm> — Requires a cascading EditContext
    8. +
+

Migration Example

+
+
+
+
<asp:ValidationSummary
+    ID="vs1"
+    HeaderText="The following errors occurred:"
+    DisplayMode="BulletList"
+    ForeColor="Red"
+    ShowMessageBox="false"
+    ShowSummary="true"
+    runat="server" />
+
+
+
+
<AspNetValidationSummary
+    HeaderText="The following errors occurred:"
+    DisplayMode="ValidationSummaryDisplayMode.BulletList"
+    ForeColor="WebColor.Red"
+    ShowSummary="true" />
+
+
+
+
+
+

ErrorMessage vs Text

+

Validators have both Text (displayed inline next to the field) and ErrorMessage (displayed in the ValidationSummary). Set both for the best user experience — a short indicator like "*" for Text and a descriptive message for ErrorMessage.

+
+

See Also

+ + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+ + + +
+
+
+
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/site/assets/BlazorWebHighRes.ico b/site/assets/BlazorWebHighRes.ico new file mode 100644 index 000000000..f0782fe0b Binary files /dev/null and b/site/assets/BlazorWebHighRes.ico differ diff --git a/site/assets/favicon.ico b/site/assets/favicon.ico new file mode 100644 index 000000000..f0782fe0b Binary files /dev/null and b/site/assets/favicon.ico differ diff --git a/site/assets/images/favicon.png b/site/assets/images/favicon.png new file mode 100644 index 000000000..1cf13b9f9 Binary files /dev/null and b/site/assets/images/favicon.png differ diff --git a/site/assets/javascripts/bundle.79ae519e.min.js b/site/assets/javascripts/bundle.79ae519e.min.js new file mode 100644 index 000000000..3df3e5e61 --- /dev/null +++ b/site/assets/javascripts/bundle.79ae519e.min.js @@ -0,0 +1,16 @@ +"use strict";(()=>{var Zi=Object.create;var _r=Object.defineProperty;var ea=Object.getOwnPropertyDescriptor;var ta=Object.getOwnPropertyNames,Bt=Object.getOwnPropertySymbols,ra=Object.getPrototypeOf,Ar=Object.prototype.hasOwnProperty,bo=Object.prototype.propertyIsEnumerable;var ho=(e,t,r)=>t in e?_r(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,P=(e,t)=>{for(var r in t||(t={}))Ar.call(t,r)&&ho(e,r,t[r]);if(Bt)for(var r of Bt(t))bo.call(t,r)&&ho(e,r,t[r]);return e};var vo=(e,t)=>{var r={};for(var o in e)Ar.call(e,o)&&t.indexOf(o)<0&&(r[o]=e[o]);if(e!=null&&Bt)for(var o of Bt(e))t.indexOf(o)<0&&bo.call(e,o)&&(r[o]=e[o]);return r};var Cr=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var oa=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of ta(t))!Ar.call(e,n)&&n!==r&&_r(e,n,{get:()=>t[n],enumerable:!(o=ea(t,n))||o.enumerable});return e};var $t=(e,t,r)=>(r=e!=null?Zi(ra(e)):{},oa(t||!e||!e.__esModule?_r(r,"default",{value:e,enumerable:!0}):r,e));var go=(e,t,r)=>new Promise((o,n)=>{var i=c=>{try{a(r.next(c))}catch(p){n(p)}},s=c=>{try{a(r.throw(c))}catch(p){n(p)}},a=c=>c.done?o(c.value):Promise.resolve(c.value).then(i,s);a((r=r.apply(e,t)).next())});var xo=Cr((kr,yo)=>{(function(e,t){typeof kr=="object"&&typeof yo!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(kr,(function(){"use strict";function e(r){var o=!0,n=!1,i=null,s={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function a(k){return!!(k&&k!==document&&k.nodeName!=="HTML"&&k.nodeName!=="BODY"&&"classList"in k&&"contains"in k.classList)}function c(k){var ut=k.type,je=k.tagName;return!!(je==="INPUT"&&s[ut]&&!k.readOnly||je==="TEXTAREA"&&!k.readOnly||k.isContentEditable)}function p(k){k.classList.contains("focus-visible")||(k.classList.add("focus-visible"),k.setAttribute("data-focus-visible-added",""))}function l(k){k.hasAttribute("data-focus-visible-added")&&(k.classList.remove("focus-visible"),k.removeAttribute("data-focus-visible-added"))}function f(k){k.metaKey||k.altKey||k.ctrlKey||(a(r.activeElement)&&p(r.activeElement),o=!0)}function u(k){o=!1}function d(k){a(k.target)&&(o||c(k.target))&&p(k.target)}function v(k){a(k.target)&&(k.target.classList.contains("focus-visible")||k.target.hasAttribute("data-focus-visible-added"))&&(n=!0,window.clearTimeout(i),i=window.setTimeout(function(){n=!1},100),l(k.target))}function S(k){document.visibilityState==="hidden"&&(n&&(o=!0),X())}function X(){document.addEventListener("mousemove",ee),document.addEventListener("mousedown",ee),document.addEventListener("mouseup",ee),document.addEventListener("pointermove",ee),document.addEventListener("pointerdown",ee),document.addEventListener("pointerup",ee),document.addEventListener("touchmove",ee),document.addEventListener("touchstart",ee),document.addEventListener("touchend",ee)}function re(){document.removeEventListener("mousemove",ee),document.removeEventListener("mousedown",ee),document.removeEventListener("mouseup",ee),document.removeEventListener("pointermove",ee),document.removeEventListener("pointerdown",ee),document.removeEventListener("pointerup",ee),document.removeEventListener("touchmove",ee),document.removeEventListener("touchstart",ee),document.removeEventListener("touchend",ee)}function ee(k){k.target.nodeName&&k.target.nodeName.toLowerCase()==="html"||(o=!1,re())}document.addEventListener("keydown",f,!0),document.addEventListener("mousedown",u,!0),document.addEventListener("pointerdown",u,!0),document.addEventListener("touchstart",u,!0),document.addEventListener("visibilitychange",S,!0),X(),r.addEventListener("focus",d,!0),r.addEventListener("blur",v,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)}))});var ro=Cr((jy,Rn)=>{"use strict";/*! + * escape-html + * Copyright(c) 2012-2013 TJ Holowaychuk + * Copyright(c) 2015 Andreas Lubbe + * Copyright(c) 2015 Tiancheng "Timothy" Gu + * MIT Licensed + */var qa=/["'&<>]/;Rn.exports=Ka;function Ka(e){var t=""+e,r=qa.exec(t);if(!r)return t;var o,n="",i=0,s=0;for(i=r.index;i{/*! + * clipboard.js v2.0.11 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */(function(t,r){typeof Nt=="object"&&typeof io=="object"?io.exports=r():typeof define=="function"&&define.amd?define([],r):typeof Nt=="object"?Nt.ClipboardJS=r():t.ClipboardJS=r()})(Nt,function(){return(function(){var e={686:(function(o,n,i){"use strict";i.d(n,{default:function(){return Xi}});var s=i(279),a=i.n(s),c=i(370),p=i.n(c),l=i(817),f=i.n(l);function u(q){try{return document.execCommand(q)}catch(C){return!1}}var d=function(C){var _=f()(C);return u("cut"),_},v=d;function S(q){var C=document.documentElement.getAttribute("dir")==="rtl",_=document.createElement("textarea");_.style.fontSize="12pt",_.style.border="0",_.style.padding="0",_.style.margin="0",_.style.position="absolute",_.style[C?"right":"left"]="-9999px";var D=window.pageYOffset||document.documentElement.scrollTop;return _.style.top="".concat(D,"px"),_.setAttribute("readonly",""),_.value=q,_}var X=function(C,_){var D=S(C);_.container.appendChild(D);var N=f()(D);return u("copy"),D.remove(),N},re=function(C){var _=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body},D="";return typeof C=="string"?D=X(C,_):C instanceof HTMLInputElement&&!["text","search","url","tel","password"].includes(C==null?void 0:C.type)?D=X(C.value,_):(D=f()(C),u("copy")),D},ee=re;function k(q){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?k=function(_){return typeof _}:k=function(_){return _&&typeof Symbol=="function"&&_.constructor===Symbol&&_!==Symbol.prototype?"symbol":typeof _},k(q)}var ut=function(){var C=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{},_=C.action,D=_===void 0?"copy":_,N=C.container,G=C.target,We=C.text;if(D!=="copy"&&D!=="cut")throw new Error('Invalid "action" value, use either "copy" or "cut"');if(G!==void 0)if(G&&k(G)==="object"&&G.nodeType===1){if(D==="copy"&&G.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if(D==="cut"&&(G.hasAttribute("readonly")||G.hasAttribute("disabled")))throw new Error(`Invalid "target" attribute. You can't cut text from elements with "readonly" or "disabled" attributes`)}else throw new Error('Invalid "target" value, use a valid Element');if(We)return ee(We,{container:N});if(G)return D==="cut"?v(G):ee(G,{container:N})},je=ut;function R(q){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?R=function(_){return typeof _}:R=function(_){return _&&typeof Symbol=="function"&&_.constructor===Symbol&&_!==Symbol.prototype?"symbol":typeof _},R(q)}function se(q,C){if(!(q instanceof C))throw new TypeError("Cannot call a class as a function")}function ce(q,C){for(var _=0;_0&&arguments[0]!==void 0?arguments[0]:{};this.action=typeof N.action=="function"?N.action:this.defaultAction,this.target=typeof N.target=="function"?N.target:this.defaultTarget,this.text=typeof N.text=="function"?N.text:this.defaultText,this.container=R(N.container)==="object"?N.container:document.body}},{key:"listenClick",value:function(N){var G=this;this.listener=p()(N,"click",function(We){return G.onClick(We)})}},{key:"onClick",value:function(N){var G=N.delegateTarget||N.currentTarget,We=this.action(G)||"copy",Yt=je({action:We,container:this.container,target:this.target(G),text:this.text(G)});this.emit(Yt?"success":"error",{action:We,text:Yt,trigger:G,clearSelection:function(){G&&G.focus(),window.getSelection().removeAllRanges()}})}},{key:"defaultAction",value:function(N){return Mr("action",N)}},{key:"defaultTarget",value:function(N){var G=Mr("target",N);if(G)return document.querySelector(G)}},{key:"defaultText",value:function(N){return Mr("text",N)}},{key:"destroy",value:function(){this.listener.destroy()}}],[{key:"copy",value:function(N){var G=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body};return ee(N,G)}},{key:"cut",value:function(N){return v(N)}},{key:"isSupported",value:function(){var N=arguments.length>0&&arguments[0]!==void 0?arguments[0]:["copy","cut"],G=typeof N=="string"?[N]:N,We=!!document.queryCommandSupported;return G.forEach(function(Yt){We=We&&!!document.queryCommandSupported(Yt)}),We}}]),_})(a()),Xi=Ji}),828:(function(o){var n=9;if(typeof Element!="undefined"&&!Element.prototype.matches){var i=Element.prototype;i.matches=i.matchesSelector||i.mozMatchesSelector||i.msMatchesSelector||i.oMatchesSelector||i.webkitMatchesSelector}function s(a,c){for(;a&&a.nodeType!==n;){if(typeof a.matches=="function"&&a.matches(c))return a;a=a.parentNode}}o.exports=s}),438:(function(o,n,i){var s=i(828);function a(l,f,u,d,v){var S=p.apply(this,arguments);return l.addEventListener(u,S,v),{destroy:function(){l.removeEventListener(u,S,v)}}}function c(l,f,u,d,v){return typeof l.addEventListener=="function"?a.apply(null,arguments):typeof u=="function"?a.bind(null,document).apply(null,arguments):(typeof l=="string"&&(l=document.querySelectorAll(l)),Array.prototype.map.call(l,function(S){return a(S,f,u,d,v)}))}function p(l,f,u,d){return function(v){v.delegateTarget=s(v.target,f),v.delegateTarget&&d.call(l,v)}}o.exports=c}),879:(function(o,n){n.node=function(i){return i!==void 0&&i instanceof HTMLElement&&i.nodeType===1},n.nodeList=function(i){var s=Object.prototype.toString.call(i);return i!==void 0&&(s==="[object NodeList]"||s==="[object HTMLCollection]")&&"length"in i&&(i.length===0||n.node(i[0]))},n.string=function(i){return typeof i=="string"||i instanceof String},n.fn=function(i){var s=Object.prototype.toString.call(i);return s==="[object Function]"}}),370:(function(o,n,i){var s=i(879),a=i(438);function c(u,d,v){if(!u&&!d&&!v)throw new Error("Missing required arguments");if(!s.string(d))throw new TypeError("Second argument must be a String");if(!s.fn(v))throw new TypeError("Third argument must be a Function");if(s.node(u))return p(u,d,v);if(s.nodeList(u))return l(u,d,v);if(s.string(u))return f(u,d,v);throw new TypeError("First argument must be a String, HTMLElement, HTMLCollection, or NodeList")}function p(u,d,v){return u.addEventListener(d,v),{destroy:function(){u.removeEventListener(d,v)}}}function l(u,d,v){return Array.prototype.forEach.call(u,function(S){S.addEventListener(d,v)}),{destroy:function(){Array.prototype.forEach.call(u,function(S){S.removeEventListener(d,v)})}}}function f(u,d,v){return a(document.body,u,d,v)}o.exports=c}),817:(function(o){function n(i){var s;if(i.nodeName==="SELECT")i.focus(),s=i.value;else if(i.nodeName==="INPUT"||i.nodeName==="TEXTAREA"){var a=i.hasAttribute("readonly");a||i.setAttribute("readonly",""),i.select(),i.setSelectionRange(0,i.value.length),a||i.removeAttribute("readonly"),s=i.value}else{i.hasAttribute("contenteditable")&&i.focus();var c=window.getSelection(),p=document.createRange();p.selectNodeContents(i),c.removeAllRanges(),c.addRange(p),s=c.toString()}return s}o.exports=n}),279:(function(o){function n(){}n.prototype={on:function(i,s,a){var c=this.e||(this.e={});return(c[i]||(c[i]=[])).push({fn:s,ctx:a}),this},once:function(i,s,a){var c=this;function p(){c.off(i,p),s.apply(a,arguments)}return p._=s,this.on(i,p,a)},emit:function(i){var s=[].slice.call(arguments,1),a=((this.e||(this.e={}))[i]||[]).slice(),c=0,p=a.length;for(c;c0&&i[i.length-1])&&(p[0]===6||p[0]===2)){r=0;continue}if(p[0]===3&&(!i||p[1]>i[0]&&p[1]=e.length&&(e=void 0),{value:e&&e[o++],done:!e}}};throw new TypeError(t?"Object is not iterable.":"Symbol.iterator is not defined.")}function K(e,t){var r=typeof Symbol=="function"&&e[Symbol.iterator];if(!r)return e;var o=r.call(e),n,i=[],s;try{for(;(t===void 0||t-- >0)&&!(n=o.next()).done;)i.push(n.value)}catch(a){s={error:a}}finally{try{n&&!n.done&&(r=o.return)&&r.call(o)}finally{if(s)throw s.error}}return i}function B(e,t,r){if(r||arguments.length===2)for(var o=0,n=t.length,i;o1||c(d,S)})},v&&(n[d]=v(n[d])))}function c(d,v){try{p(o[d](v))}catch(S){u(i[0][3],S)}}function p(d){d.value instanceof dt?Promise.resolve(d.value.v).then(l,f):u(i[0][2],d)}function l(d){c("next",d)}function f(d){c("throw",d)}function u(d,v){d(v),i.shift(),i.length&&c(i[0][0],i[0][1])}}function To(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t=e[Symbol.asyncIterator],r;return t?t.call(e):(e=typeof Oe=="function"?Oe(e):e[Symbol.iterator](),r={},o("next"),o("throw"),o("return"),r[Symbol.asyncIterator]=function(){return this},r);function o(i){r[i]=e[i]&&function(s){return new Promise(function(a,c){s=e[i](s),n(a,c,s.done,s.value)})}}function n(i,s,a,c){Promise.resolve(c).then(function(p){i({value:p,done:a})},s)}}function I(e){return typeof e=="function"}function yt(e){var t=function(o){Error.call(o),o.stack=new Error().stack},r=e(t);return r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r}var Jt=yt(function(e){return function(r){e(this),this.message=r?r.length+` errors occurred during unsubscription: +`+r.map(function(o,n){return n+1+") "+o.toString()}).join(` + `):"",this.name="UnsubscriptionError",this.errors=r}});function Ze(e,t){if(e){var r=e.indexOf(t);0<=r&&e.splice(r,1)}}var qe=(function(){function e(t){this.initialTeardown=t,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var t,r,o,n,i;if(!this.closed){this.closed=!0;var s=this._parentage;if(s)if(this._parentage=null,Array.isArray(s))try{for(var a=Oe(s),c=a.next();!c.done;c=a.next()){var p=c.value;p.remove(this)}}catch(S){t={error:S}}finally{try{c&&!c.done&&(r=a.return)&&r.call(a)}finally{if(t)throw t.error}}else s.remove(this);var l=this.initialTeardown;if(I(l))try{l()}catch(S){i=S instanceof Jt?S.errors:[S]}var f=this._finalizers;if(f){this._finalizers=null;try{for(var u=Oe(f),d=u.next();!d.done;d=u.next()){var v=d.value;try{So(v)}catch(S){i=i!=null?i:[],S instanceof Jt?i=B(B([],K(i)),K(S.errors)):i.push(S)}}}catch(S){o={error:S}}finally{try{d&&!d.done&&(n=u.return)&&n.call(u)}finally{if(o)throw o.error}}}if(i)throw new Jt(i)}},e.prototype.add=function(t){var r;if(t&&t!==this)if(this.closed)So(t);else{if(t instanceof e){if(t.closed||t._hasParent(this))return;t._addParent(this)}(this._finalizers=(r=this._finalizers)!==null&&r!==void 0?r:[]).push(t)}},e.prototype._hasParent=function(t){var r=this._parentage;return r===t||Array.isArray(r)&&r.includes(t)},e.prototype._addParent=function(t){var r=this._parentage;this._parentage=Array.isArray(r)?(r.push(t),r):r?[r,t]:t},e.prototype._removeParent=function(t){var r=this._parentage;r===t?this._parentage=null:Array.isArray(r)&&Ze(r,t)},e.prototype.remove=function(t){var r=this._finalizers;r&&Ze(r,t),t instanceof e&&t._removeParent(this)},e.EMPTY=(function(){var t=new e;return t.closed=!0,t})(),e})();var $r=qe.EMPTY;function Xt(e){return e instanceof qe||e&&"closed"in e&&I(e.remove)&&I(e.add)&&I(e.unsubscribe)}function So(e){I(e)?e():e.unsubscribe()}var De={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var xt={setTimeout:function(e,t){for(var r=[],o=2;o0},enumerable:!1,configurable:!0}),t.prototype._trySubscribe=function(r){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,r)},t.prototype._subscribe=function(r){return this._throwIfClosed(),this._checkFinalizedStatuses(r),this._innerSubscribe(r)},t.prototype._innerSubscribe=function(r){var o=this,n=this,i=n.hasError,s=n.isStopped,a=n.observers;return i||s?$r:(this.currentObservers=null,a.push(r),new qe(function(){o.currentObservers=null,Ze(a,r)}))},t.prototype._checkFinalizedStatuses=function(r){var o=this,n=o.hasError,i=o.thrownError,s=o.isStopped;n?r.error(i):s&&r.complete()},t.prototype.asObservable=function(){var r=new F;return r.source=this,r},t.create=function(r,o){return new Ho(r,o)},t})(F);var Ho=(function(e){ie(t,e);function t(r,o){var n=e.call(this)||this;return n.destination=r,n.source=o,n}return t.prototype.next=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.next)===null||n===void 0||n.call(o,r)},t.prototype.error=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.error)===null||n===void 0||n.call(o,r)},t.prototype.complete=function(){var r,o;(o=(r=this.destination)===null||r===void 0?void 0:r.complete)===null||o===void 0||o.call(r)},t.prototype._subscribe=function(r){var o,n;return(n=(o=this.source)===null||o===void 0?void 0:o.subscribe(r))!==null&&n!==void 0?n:$r},t})(T);var jr=(function(e){ie(t,e);function t(r){var o=e.call(this)||this;return o._value=r,o}return Object.defineProperty(t.prototype,"value",{get:function(){return this.getValue()},enumerable:!1,configurable:!0}),t.prototype._subscribe=function(r){var o=e.prototype._subscribe.call(this,r);return!o.closed&&r.next(this._value),o},t.prototype.getValue=function(){var r=this,o=r.hasError,n=r.thrownError,i=r._value;if(o)throw n;return this._throwIfClosed(),i},t.prototype.next=function(r){e.prototype.next.call(this,this._value=r)},t})(T);var Rt={now:function(){return(Rt.delegate||Date).now()},delegate:void 0};var It=(function(e){ie(t,e);function t(r,o,n){r===void 0&&(r=1/0),o===void 0&&(o=1/0),n===void 0&&(n=Rt);var i=e.call(this)||this;return i._bufferSize=r,i._windowTime=o,i._timestampProvider=n,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=o===1/0,i._bufferSize=Math.max(1,r),i._windowTime=Math.max(1,o),i}return t.prototype.next=function(r){var o=this,n=o.isStopped,i=o._buffer,s=o._infiniteTimeWindow,a=o._timestampProvider,c=o._windowTime;n||(i.push(r),!s&&i.push(a.now()+c)),this._trimBuffer(),e.prototype.next.call(this,r)},t.prototype._subscribe=function(r){this._throwIfClosed(),this._trimBuffer();for(var o=this._innerSubscribe(r),n=this,i=n._infiniteTimeWindow,s=n._buffer,a=s.slice(),c=0;c0?e.prototype.schedule.call(this,r,o):(this.delay=o,this.state=r,this.scheduler.flush(this),this)},t.prototype.execute=function(r,o){return o>0||this.closed?e.prototype.execute.call(this,r,o):this._execute(r,o)},t.prototype.requestAsyncId=function(r,o,n){return n===void 0&&(n=0),n!=null&&n>0||n==null&&this.delay>0?e.prototype.requestAsyncId.call(this,r,o,n):(r.flush(this),0)},t})(St);var Ro=(function(e){ie(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t})(Ot);var Dr=new Ro(Po);var Io=(function(e){ie(t,e);function t(r,o){var n=e.call(this,r,o)||this;return n.scheduler=r,n.work=o,n}return t.prototype.requestAsyncId=function(r,o,n){return n===void 0&&(n=0),n!==null&&n>0?e.prototype.requestAsyncId.call(this,r,o,n):(r.actions.push(this),r._scheduled||(r._scheduled=Tt.requestAnimationFrame(function(){return r.flush(void 0)})))},t.prototype.recycleAsyncId=function(r,o,n){var i;if(n===void 0&&(n=0),n!=null?n>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,r,o,n);var s=r.actions;o!=null&&o===r._scheduled&&((i=s[s.length-1])===null||i===void 0?void 0:i.id)!==o&&(Tt.cancelAnimationFrame(o),r._scheduled=void 0)},t})(St);var Fo=(function(e){ie(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t.prototype.flush=function(r){this._active=!0;var o;r?o=r.id:(o=this._scheduled,this._scheduled=void 0);var n=this.actions,i;r=r||n.shift();do if(i=r.execute(r.state,r.delay))break;while((r=n[0])&&r.id===o&&n.shift());if(this._active=!1,i){for(;(r=n[0])&&r.id===o&&n.shift();)r.unsubscribe();throw i}},t})(Ot);var ye=new Fo(Io);var y=new F(function(e){return e.complete()});function tr(e){return e&&I(e.schedule)}function Vr(e){return e[e.length-1]}function pt(e){return I(Vr(e))?e.pop():void 0}function Fe(e){return tr(Vr(e))?e.pop():void 0}function rr(e,t){return typeof Vr(e)=="number"?e.pop():t}var Lt=(function(e){return e&&typeof e.length=="number"&&typeof e!="function"});function or(e){return I(e==null?void 0:e.then)}function nr(e){return I(e[wt])}function ir(e){return Symbol.asyncIterator&&I(e==null?void 0:e[Symbol.asyncIterator])}function ar(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function fa(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var sr=fa();function cr(e){return I(e==null?void 0:e[sr])}function pr(e){return wo(this,arguments,function(){var r,o,n,i;return Gt(this,function(s){switch(s.label){case 0:r=e.getReader(),s.label=1;case 1:s.trys.push([1,,9,10]),s.label=2;case 2:return[4,dt(r.read())];case 3:return o=s.sent(),n=o.value,i=o.done,i?[4,dt(void 0)]:[3,5];case 4:return[2,s.sent()];case 5:return[4,dt(n)];case 6:return[4,s.sent()];case 7:return s.sent(),[3,2];case 8:return[3,10];case 9:return r.releaseLock(),[7];case 10:return[2]}})})}function lr(e){return I(e==null?void 0:e.getReader)}function U(e){if(e instanceof F)return e;if(e!=null){if(nr(e))return ua(e);if(Lt(e))return da(e);if(or(e))return ha(e);if(ir(e))return jo(e);if(cr(e))return ba(e);if(lr(e))return va(e)}throw ar(e)}function ua(e){return new F(function(t){var r=e[wt]();if(I(r.subscribe))return r.subscribe(t);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function da(e){return new F(function(t){for(var r=0;r=2;return function(o){return o.pipe(e?g(function(n,i){return e(n,i,o)}):be,Ee(1),r?Qe(t):tn(function(){return new fr}))}}function Yr(e){return e<=0?function(){return y}:E(function(t,r){var o=[];t.subscribe(w(r,function(n){o.push(n),e=2,!0))}function le(e){e===void 0&&(e={});var t=e.connector,r=t===void 0?function(){return new T}:t,o=e.resetOnError,n=o===void 0?!0:o,i=e.resetOnComplete,s=i===void 0?!0:i,a=e.resetOnRefCountZero,c=a===void 0?!0:a;return function(p){var l,f,u,d=0,v=!1,S=!1,X=function(){f==null||f.unsubscribe(),f=void 0},re=function(){X(),l=u=void 0,v=S=!1},ee=function(){var k=l;re(),k==null||k.unsubscribe()};return E(function(k,ut){d++,!S&&!v&&X();var je=u=u!=null?u:r();ut.add(function(){d--,d===0&&!S&&!v&&(f=Br(ee,c))}),je.subscribe(ut),!l&&d>0&&(l=new bt({next:function(R){return je.next(R)},error:function(R){S=!0,X(),f=Br(re,n,R),je.error(R)},complete:function(){v=!0,X(),f=Br(re,s),je.complete()}}),U(k).subscribe(l))})(p)}}function Br(e,t){for(var r=[],o=2;oe.next(document)),e}function M(e,t=document){return Array.from(t.querySelectorAll(e))}function j(e,t=document){let r=ue(e,t);if(typeof r=="undefined")throw new ReferenceError(`Missing element: expected "${e}" to be present`);return r}function ue(e,t=document){return t.querySelector(e)||void 0}function Ne(){var e,t,r,o;return(o=(r=(t=(e=document.activeElement)==null?void 0:e.shadowRoot)==null?void 0:t.activeElement)!=null?r:document.activeElement)!=null?o:void 0}var Ra=L(h(document.body,"focusin"),h(document.body,"focusout")).pipe(Ae(1),Q(void 0),m(()=>Ne()||document.body),Z(1));function Ye(e){return Ra.pipe(m(t=>e.contains(t)),Y())}function it(e,t){return H(()=>L(h(e,"mouseenter").pipe(m(()=>!0)),h(e,"mouseleave").pipe(m(()=>!1))).pipe(t?jt(r=>He(+!r*t)):be,Q(e.matches(":hover"))))}function sn(e,t){if(typeof t=="string"||typeof t=="number")e.innerHTML+=t.toString();else if(t instanceof Node)e.appendChild(t);else if(Array.isArray(t))for(let r of t)sn(e,r)}function x(e,t,...r){let o=document.createElement(e);if(t)for(let n of Object.keys(t))typeof t[n]!="undefined"&&(typeof t[n]!="boolean"?o.setAttribute(n,t[n]):o.setAttribute(n,""));for(let n of r)sn(o,n);return o}function br(e){if(e>999){let t=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(t)}k`}else return e.toString()}function _t(e){let t=x("script",{src:e});return H(()=>(document.head.appendChild(t),L(h(t,"load"),h(t,"error").pipe(b(()=>Nr(()=>new ReferenceError(`Invalid script: ${e}`))))).pipe(m(()=>{}),A(()=>document.head.removeChild(t)),Ee(1))))}var cn=new T,Ia=H(()=>typeof ResizeObserver=="undefined"?_t("https://unpkg.com/resize-observer-polyfill"):$(void 0)).pipe(m(()=>new ResizeObserver(e=>e.forEach(t=>cn.next(t)))),b(e=>L(tt,$(e)).pipe(A(()=>e.disconnect()))),Z(1));function de(e){return{width:e.offsetWidth,height:e.offsetHeight}}function Le(e){let t=e;for(;t.clientWidth===0&&t.parentElement;)t=t.parentElement;return Ia.pipe(O(r=>r.observe(t)),b(r=>cn.pipe(g(o=>o.target===t),A(()=>r.unobserve(t)))),m(()=>de(e)),Q(de(e)))}function At(e){return{width:e.scrollWidth,height:e.scrollHeight}}function vr(e){let t=e.parentElement;for(;t&&(e.scrollWidth<=t.scrollWidth&&e.scrollHeight<=t.scrollHeight);)t=(e=t).parentElement;return t?e:void 0}function pn(e){let t=[],r=e.parentElement;for(;r;)(e.clientWidth>r.clientWidth||e.clientHeight>r.clientHeight)&&t.push(r),r=(e=r).parentElement;return t.length===0&&t.push(document.documentElement),t}function Be(e){return{x:e.offsetLeft,y:e.offsetTop}}function ln(e){let t=e.getBoundingClientRect();return{x:t.x+window.scrollX,y:t.y+window.scrollY}}function mn(e){return L(h(window,"load"),h(window,"resize")).pipe($e(0,ye),m(()=>Be(e)),Q(Be(e)))}function gr(e){return{x:e.scrollLeft,y:e.scrollTop}}function Ge(e){return L(h(e,"scroll"),h(window,"scroll"),h(window,"resize")).pipe($e(0,ye),m(()=>gr(e)),Q(gr(e)))}var fn=new T,Fa=H(()=>$(new IntersectionObserver(e=>{for(let t of e)fn.next(t)},{threshold:0}))).pipe(b(e=>L(tt,$(e)).pipe(A(()=>e.disconnect()))),Z(1));function mt(e){return Fa.pipe(O(t=>t.observe(e)),b(t=>fn.pipe(g(({target:r})=>r===e),A(()=>t.unobserve(e)),m(({isIntersecting:r})=>r))))}function un(e,t=16){return Ge(e).pipe(m(({y:r})=>{let o=de(e),n=At(e);return r>=n.height-o.height-t}),Y())}var yr={drawer:j("[data-md-toggle=drawer]"),search:j("[data-md-toggle=search]")};function dn(e){return yr[e].checked}function at(e,t){yr[e].checked!==t&&yr[e].click()}function Je(e){let t=yr[e];return h(t,"change").pipe(m(()=>t.checked),Q(t.checked))}function ja(e,t){switch(e.constructor){case HTMLInputElement:return e.type==="radio"?/^Arrow/.test(t):!0;case HTMLSelectElement:case HTMLTextAreaElement:return!0;default:return e.isContentEditable}}function Ua(){return L(h(window,"compositionstart").pipe(m(()=>!0)),h(window,"compositionend").pipe(m(()=>!1))).pipe(Q(!1))}function hn(){let e=h(window,"keydown").pipe(g(t=>!(t.metaKey||t.ctrlKey)),m(t=>({mode:dn("search")?"search":"global",type:t.key,claim(){t.preventDefault(),t.stopPropagation()}})),g(({mode:t,type:r})=>{if(t==="global"){let o=Ne();if(typeof o!="undefined")return!ja(o,r)}return!0}),le());return Ua().pipe(b(t=>t?y:e))}function we(){return new URL(location.href)}function st(e,t=!1){if(V("navigation.instant")&&!t){let r=x("a",{href:e.href});document.body.appendChild(r),r.click(),r.remove()}else location.href=e.href}function bn(){return new T}function vn(){return location.hash.slice(1)}function gn(e){let t=x("a",{href:e});t.addEventListener("click",r=>r.stopPropagation()),t.click()}function Zr(e){return L(h(window,"hashchange"),e).pipe(m(vn),Q(vn()),g(t=>t.length>0),Z(1))}function yn(e){return Zr(e).pipe(m(t=>ue(`[id="${t}"]`)),g(t=>typeof t!="undefined"))}function Wt(e){let t=matchMedia(e);return ur(r=>t.addListener(()=>r(t.matches))).pipe(Q(t.matches))}function xn(){let e=matchMedia("print");return L(h(window,"beforeprint").pipe(m(()=>!0)),h(window,"afterprint").pipe(m(()=>!1))).pipe(Q(e.matches))}function eo(e,t){return e.pipe(b(r=>r?t():y))}function to(e,t){return new F(r=>{let o=new XMLHttpRequest;return o.open("GET",`${e}`),o.responseType="blob",o.addEventListener("load",()=>{o.status>=200&&o.status<300?(r.next(o.response),r.complete()):r.error(new Error(o.statusText))}),o.addEventListener("error",()=>{r.error(new Error("Network error"))}),o.addEventListener("abort",()=>{r.complete()}),typeof(t==null?void 0:t.progress$)!="undefined"&&(o.addEventListener("progress",n=>{var i;if(n.lengthComputable)t.progress$.next(n.loaded/n.total*100);else{let s=(i=o.getResponseHeader("Content-Length"))!=null?i:0;t.progress$.next(n.loaded/+s*100)}}),t.progress$.next(5)),o.send(),()=>o.abort()})}function ze(e,t){return to(e,t).pipe(b(r=>r.text()),m(r=>JSON.parse(r)),Z(1))}function xr(e,t){let r=new DOMParser;return to(e,t).pipe(b(o=>o.text()),m(o=>r.parseFromString(o,"text/html")),Z(1))}function En(e,t){let r=new DOMParser;return to(e,t).pipe(b(o=>o.text()),m(o=>r.parseFromString(o,"text/xml")),Z(1))}function wn(){return{x:Math.max(0,scrollX),y:Math.max(0,scrollY)}}function Tn(){return L(h(window,"scroll",{passive:!0}),h(window,"resize",{passive:!0})).pipe(m(wn),Q(wn()))}function Sn(){return{width:innerWidth,height:innerHeight}}function On(){return h(window,"resize",{passive:!0}).pipe(m(Sn),Q(Sn()))}function Ln(){return z([Tn(),On()]).pipe(m(([e,t])=>({offset:e,size:t})),Z(1))}function Er(e,{viewport$:t,header$:r}){let o=t.pipe(ne("size")),n=z([o,r]).pipe(m(()=>Be(e)));return z([r,t,n]).pipe(m(([{height:i},{offset:s,size:a},{x:c,y:p}])=>({offset:{x:s.x-c,y:s.y-p+i},size:a})))}function Wa(e){return h(e,"message",t=>t.data)}function Da(e){let t=new T;return t.subscribe(r=>e.postMessage(r)),t}function Mn(e,t=new Worker(e)){let r=Wa(t),o=Da(t),n=new T;n.subscribe(o);let i=o.pipe(oe(),ae(!0));return n.pipe(oe(),Ve(r.pipe(W(i))),le())}var Va=j("#__config"),Ct=JSON.parse(Va.textContent);Ct.base=`${new URL(Ct.base,we())}`;function Te(){return Ct}function V(e){return Ct.features.includes(e)}function Me(e,t){return typeof t!="undefined"?Ct.translations[e].replace("#",t.toString()):Ct.translations[e]}function Ce(e,t=document){return j(`[data-md-component=${e}]`,t)}function me(e,t=document){return M(`[data-md-component=${e}]`,t)}function Na(e){let t=j(".md-typeset > :first-child",e);return h(t,"click",{once:!0}).pipe(m(()=>j(".md-typeset",e)),m(r=>({hash:__md_hash(r.innerHTML)})))}function _n(e){if(!V("announce.dismiss")||!e.childElementCount)return y;if(!e.hidden){let t=j(".md-typeset",e);__md_hash(t.innerHTML)===__md_get("__announce")&&(e.hidden=!0)}return H(()=>{let t=new T;return t.subscribe(({hash:r})=>{e.hidden=!0,__md_set("__announce",r)}),Na(e).pipe(O(r=>t.next(r)),A(()=>t.complete()),m(r=>P({ref:e},r)))})}function za(e,{target$:t}){return t.pipe(m(r=>({hidden:r!==e})))}function An(e,t){let r=new T;return r.subscribe(({hidden:o})=>{e.hidden=o}),za(e,t).pipe(O(o=>r.next(o)),A(()=>r.complete()),m(o=>P({ref:e},o)))}function Dt(e,t){return t==="inline"?x("div",{class:"md-tooltip md-tooltip--inline",id:e,role:"tooltip"},x("div",{class:"md-tooltip__inner md-typeset"})):x("div",{class:"md-tooltip",id:e,role:"tooltip"},x("div",{class:"md-tooltip__inner md-typeset"}))}function wr(...e){return x("div",{class:"md-tooltip2",role:"dialog"},x("div",{class:"md-tooltip2__inner md-typeset"},e))}function Cn(...e){return x("div",{class:"md-tooltip2",role:"tooltip"},x("div",{class:"md-tooltip2__inner md-typeset"},e))}function kn(e,t){if(t=t?`${t}_annotation_${e}`:void 0,t){let r=t?`#${t}`:void 0;return x("aside",{class:"md-annotation",tabIndex:0},Dt(t),x("a",{href:r,class:"md-annotation__index",tabIndex:-1},x("span",{"data-md-annotation-id":e})))}else return x("aside",{class:"md-annotation",tabIndex:0},Dt(t),x("span",{class:"md-annotation__index",tabIndex:-1},x("span",{"data-md-annotation-id":e})))}function Hn(e){return x("button",{class:"md-code__button",title:Me("clipboard.copy"),"data-clipboard-target":`#${e} > code`,"data-md-type":"copy"})}function $n(){return x("button",{class:"md-code__button",title:"Toggle line selection","data-md-type":"select"})}function Pn(){return x("nav",{class:"md-code__nav"})}var In=$t(ro());function oo(e,t){let r=t&2,o=t&1,n=Object.keys(e.terms).filter(c=>!e.terms[c]).reduce((c,p)=>[...c,x("del",null,(0,In.default)(p))," "],[]).slice(0,-1),i=Te(),s=new URL(e.location,i.base);V("search.highlight")&&s.searchParams.set("h",Object.entries(e.terms).filter(([,c])=>c).reduce((c,[p])=>`${c} ${p}`.trim(),""));let{tags:a}=Te();return x("a",{href:`${s}`,class:"md-search-result__link",tabIndex:-1},x("article",{class:"md-search-result__article md-typeset","data-md-score":e.score.toFixed(2)},r>0&&x("div",{class:"md-search-result__icon md-icon"}),r>0&&x("h1",null,e.title),r<=0&&x("h2",null,e.title),o>0&&e.text.length>0&&e.text,e.tags&&x("nav",{class:"md-tags"},e.tags.map(c=>{let p=a?c in a?`md-tag-icon md-tag--${a[c]}`:"md-tag-icon":"";return x("span",{class:`md-tag ${p}`},c)})),o>0&&n.length>0&&x("p",{class:"md-search-result__terms"},Me("search.result.term.missing"),": ",...n)))}function Fn(e){let t=e[0].score,r=[...e],o=Te(),n=r.findIndex(l=>!`${new URL(l.location,o.base)}`.includes("#")),[i]=r.splice(n,1),s=r.findIndex(l=>l.scoreoo(l,1)),...c.length?[x("details",{class:"md-search-result__more"},x("summary",{tabIndex:-1},x("div",null,c.length>0&&c.length===1?Me("search.result.more.one"):Me("search.result.more.other",c.length))),...c.map(l=>oo(l,1)))]:[]];return x("li",{class:"md-search-result__item"},p)}function jn(e){return x("ul",{class:"md-source__facts"},Object.entries(e).map(([t,r])=>x("li",{class:`md-source__fact md-source__fact--${t}`},typeof r=="number"?br(r):r)))}function no(e){let t=`tabbed-control tabbed-control--${e}`;return x("div",{class:t,hidden:!0},x("button",{class:"tabbed-button",tabIndex:-1,"aria-hidden":"true"}))}function Un(e){return x("div",{class:"md-typeset__scrollwrap"},x("div",{class:"md-typeset__table"},e))}function Qa(e){var o;let t=Te(),r=new URL(`../${e.version}/`,t.base);return x("li",{class:"md-version__item"},x("a",{href:`${r}`,class:"md-version__link"},e.title,((o=t.version)==null?void 0:o.alias)&&e.aliases.length>0&&x("span",{class:"md-version__alias"},e.aliases[0])))}function Wn(e,t){var o;let r=Te();return e=e.filter(n=>{var i;return!((i=n.properties)!=null&&i.hidden)}),x("div",{class:"md-version"},x("button",{class:"md-version__current","aria-label":Me("select.version")},t.title,((o=r.version)==null?void 0:o.alias)&&t.aliases.length>0&&x("span",{class:"md-version__alias"},t.aliases[0])),x("ul",{class:"md-version__list"},e.map(Qa)))}var Ya=0;function Ba(e,t=250){let r=z([Ye(e),it(e,t)]).pipe(m(([n,i])=>n||i),Y()),o=H(()=>pn(e)).pipe(J(Ge),gt(1),Pe(r),m(()=>ln(e)));return r.pipe(Re(n=>n),b(()=>z([r,o])),m(([n,i])=>({active:n,offset:i})),le())}function Vt(e,t,r=250){let{content$:o,viewport$:n}=t,i=`__tooltip2_${Ya++}`;return H(()=>{let s=new T,a=new jr(!1);s.pipe(oe(),ae(!1)).subscribe(a);let c=a.pipe(jt(l=>He(+!l*250,Dr)),Y(),b(l=>l?o:y),O(l=>l.id=i),le());z([s.pipe(m(({active:l})=>l)),c.pipe(b(l=>it(l,250)),Q(!1))]).pipe(m(l=>l.some(f=>f))).subscribe(a);let p=a.pipe(g(l=>l),te(c,n),m(([l,f,{size:u}])=>{let d=e.getBoundingClientRect(),v=d.width/2;if(f.role==="tooltip")return{x:v,y:8+d.height};if(d.y>=u.height/2){let{height:S}=de(f);return{x:v,y:-16-S}}else return{x:v,y:16+d.height}}));return z([c,s,p]).subscribe(([l,{offset:f},u])=>{l.style.setProperty("--md-tooltip-host-x",`${f.x}px`),l.style.setProperty("--md-tooltip-host-y",`${f.y}px`),l.style.setProperty("--md-tooltip-x",`${u.x}px`),l.style.setProperty("--md-tooltip-y",`${u.y}px`),l.classList.toggle("md-tooltip2--top",u.y<0),l.classList.toggle("md-tooltip2--bottom",u.y>=0)}),a.pipe(g(l=>l),te(c,(l,f)=>f),g(l=>l.role==="tooltip")).subscribe(l=>{let f=de(j(":scope > *",l));l.style.setProperty("--md-tooltip-width",`${f.width}px`),l.style.setProperty("--md-tooltip-tail","0px")}),a.pipe(Y(),xe(ye),te(c)).subscribe(([l,f])=>{f.classList.toggle("md-tooltip2--active",l)}),z([a.pipe(g(l=>l)),c]).subscribe(([l,f])=>{f.role==="dialog"?(e.setAttribute("aria-controls",i),e.setAttribute("aria-haspopup","dialog")):e.setAttribute("aria-describedby",i)}),a.pipe(g(l=>!l)).subscribe(()=>{e.removeAttribute("aria-controls"),e.removeAttribute("aria-describedby"),e.removeAttribute("aria-haspopup")}),Ba(e,r).pipe(O(l=>s.next(l)),A(()=>s.complete()),m(l=>P({ref:e},l)))})}function Xe(e,{viewport$:t},r=document.body){return Vt(e,{content$:new F(o=>{let n=e.title,i=Cn(n);return o.next(i),e.removeAttribute("title"),r.append(i),()=>{i.remove(),e.setAttribute("title",n)}}),viewport$:t},0)}function Ga(e,t){let r=H(()=>z([mn(e),Ge(t)])).pipe(m(([{x:o,y:n},i])=>{let{width:s,height:a}=de(e);return{x:o-i.x+s/2,y:n-i.y+a/2}}));return Ye(e).pipe(b(o=>r.pipe(m(n=>({active:o,offset:n})),Ee(+!o||1/0))))}function Dn(e,t,{target$:r}){let[o,n]=Array.from(e.children);return H(()=>{let i=new T,s=i.pipe(oe(),ae(!0));return i.subscribe({next({offset:a}){e.style.setProperty("--md-tooltip-x",`${a.x}px`),e.style.setProperty("--md-tooltip-y",`${a.y}px`)},complete(){e.style.removeProperty("--md-tooltip-x"),e.style.removeProperty("--md-tooltip-y")}}),mt(e).pipe(W(s)).subscribe(a=>{e.toggleAttribute("data-md-visible",a)}),L(i.pipe(g(({active:a})=>a)),i.pipe(Ae(250),g(({active:a})=>!a))).subscribe({next({active:a}){a?e.prepend(o):o.remove()},complete(){e.prepend(o)}}),i.pipe($e(16,ye)).subscribe(({active:a})=>{o.classList.toggle("md-tooltip--active",a)}),i.pipe(gt(125,ye),g(()=>!!e.offsetParent),m(()=>e.offsetParent.getBoundingClientRect()),m(({x:a})=>a)).subscribe({next(a){a?e.style.setProperty("--md-tooltip-0",`${-a}px`):e.style.removeProperty("--md-tooltip-0")},complete(){e.style.removeProperty("--md-tooltip-0")}}),h(n,"click").pipe(W(s),g(a=>!(a.metaKey||a.ctrlKey))).subscribe(a=>{a.stopPropagation(),a.preventDefault()}),h(n,"mousedown").pipe(W(s),te(i)).subscribe(([a,{active:c}])=>{var p;if(a.button!==0||a.metaKey||a.ctrlKey)a.preventDefault();else if(c){a.preventDefault();let l=e.parentElement.closest(".md-annotation");l instanceof HTMLElement?l.focus():(p=Ne())==null||p.blur()}}),r.pipe(W(s),g(a=>a===o),nt(125)).subscribe(()=>e.focus()),Ga(e,t).pipe(O(a=>i.next(a)),A(()=>i.complete()),m(a=>P({ref:e},a)))})}function Ja(e){let t=Te();if(e.tagName!=="CODE")return[e];let r=[".c",".c1",".cm"];if(t.annotate&&typeof t.annotate=="object"){let o=e.closest("[class|=language]");if(o)for(let n of Array.from(o.classList)){if(!n.startsWith("language-"))continue;let[,i]=n.split("-");i in t.annotate&&r.push(...t.annotate[i])}}return M(r.join(", "),e)}function Xa(e){let t=[];for(let r of Ja(e)){let o=[],n=document.createNodeIterator(r,NodeFilter.SHOW_TEXT);for(let i=n.nextNode();i;i=n.nextNode())o.push(i);for(let i of o){let s;for(;s=/(\(\d+\))(!)?/.exec(i.textContent);){let[,a,c]=s;if(typeof c=="undefined"){let p=i.splitText(s.index);i=p.splitText(a.length),t.push(p)}else{i.textContent=a,t.push(i);break}}}}return t}function Vn(e,t){t.append(...Array.from(e.childNodes))}function Tr(e,t,{target$:r,print$:o}){let n=t.closest("[id]"),i=n==null?void 0:n.id,s=new Map;for(let a of Xa(t)){let[,c]=a.textContent.match(/\((\d+)\)/);ue(`:scope > li:nth-child(${c})`,e)&&(s.set(c,kn(c,i)),a.replaceWith(s.get(c)))}return s.size===0?y:H(()=>{let a=new T,c=a.pipe(oe(),ae(!0)),p=[];for(let[l,f]of s)p.push([j(".md-typeset",f),j(`:scope > li:nth-child(${l})`,e)]);return o.pipe(W(c)).subscribe(l=>{e.hidden=!l,e.classList.toggle("md-annotation-list",l);for(let[f,u]of p)l?Vn(f,u):Vn(u,f)}),L(...[...s].map(([,l])=>Dn(l,t,{target$:r}))).pipe(A(()=>a.complete()),le())})}function Nn(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return Nn(t)}}function zn(e,t){return H(()=>{let r=Nn(e);return typeof r!="undefined"?Tr(r,e,t):y})}var Kn=$t(ao());var Za=0,qn=L(h(window,"keydown").pipe(m(()=>!0)),L(h(window,"keyup"),h(window,"contextmenu")).pipe(m(()=>!1))).pipe(Q(!1),Z(1));function Qn(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return Qn(t)}}function es(e){return Le(e).pipe(m(({width:t})=>({scrollable:At(e).width>t})),ne("scrollable"))}function Yn(e,t){let{matches:r}=matchMedia("(hover)"),o=H(()=>{let n=new T,i=n.pipe(Yr(1));n.subscribe(({scrollable:d})=>{d&&r?e.setAttribute("tabindex","0"):e.removeAttribute("tabindex")});let s=[],a=e.closest("pre"),c=a.closest("[id]"),p=c?c.id:Za++;a.id=`__code_${p}`;let l=[],f=e.closest(".highlight");if(f instanceof HTMLElement){let d=Qn(f);if(typeof d!="undefined"&&(f.classList.contains("annotate")||V("content.code.annotate"))){let v=Tr(d,e,t);l.push(Le(f).pipe(W(i),m(({width:S,height:X})=>S&&X),Y(),b(S=>S?v:y)))}}let u=M(":scope > span[id]",e);if(u.length&&(e.classList.add("md-code__content"),e.closest(".select")||V("content.code.select")&&!e.closest(".no-select"))){let d=+u[0].id.split("-").pop(),v=$n();s.push(v),V("content.tooltips")&&l.push(Xe(v,{viewport$}));let S=h(v,"click").pipe(Ut(R=>!R,!1),O(()=>v.blur()),le());S.subscribe(R=>{v.classList.toggle("md-code__button--active",R)});let X=fe(u).pipe(J(R=>it(R).pipe(m(se=>[R,se]))));S.pipe(b(R=>R?X:y)).subscribe(([R,se])=>{let ce=ue(".hll.select",R);if(ce&&!se)ce.replaceWith(...Array.from(ce.childNodes));else if(!ce&&se){let he=document.createElement("span");he.className="hll select",he.append(...Array.from(R.childNodes).slice(1)),R.append(he)}});let re=fe(u).pipe(J(R=>h(R,"mousedown").pipe(O(se=>se.preventDefault()),m(()=>R)))),ee=S.pipe(b(R=>R?re:y),te(qn),m(([R,se])=>{var he;let ce=u.indexOf(R)+d;if(se===!1)return[ce,ce];{let Se=M(".hll",e).map(Ue=>u.indexOf(Ue.parentElement)+d);return(he=window.getSelection())==null||he.removeAllRanges(),[Math.min(ce,...Se),Math.max(ce,...Se)]}})),k=Zr(y).pipe(g(R=>R.startsWith(`__codelineno-${p}-`)));k.subscribe(R=>{let[,,se]=R.split("-"),ce=se.split(":").map(Se=>+Se-d+1);ce.length===1&&ce.push(ce[0]);for(let Se of M(".hll:not(.select)",e))Se.replaceWith(...Array.from(Se.childNodes));let he=u.slice(ce[0]-1,ce[1]);for(let Se of he){let Ue=document.createElement("span");Ue.className="hll",Ue.append(...Array.from(Se.childNodes).slice(1)),Se.append(Ue)}}),k.pipe(Ee(1),xe(pe)).subscribe(R=>{if(R.includes(":")){let se=document.getElementById(R.split(":")[0]);se&&setTimeout(()=>{let ce=se,he=-64;for(;ce!==document.body;)he+=ce.offsetTop,ce=ce.offsetParent;window.scrollTo({top:he})},1)}});let je=fe(M('a[href^="#__codelineno"]',f)).pipe(J(R=>h(R,"click").pipe(O(se=>se.preventDefault()),m(()=>R)))).pipe(W(i),te(qn),m(([R,se])=>{let he=+j(`[id="${R.hash.slice(1)}"]`).parentElement.id.split("-").pop();if(se===!1)return[he,he];{let Se=M(".hll",e).map(Ue=>+Ue.parentElement.id.split("-").pop());return[Math.min(he,...Se),Math.max(he,...Se)]}}));L(ee,je).subscribe(R=>{let se=`#__codelineno-${p}-`;R[0]===R[1]?se+=R[0]:se+=`${R[0]}:${R[1]}`,history.replaceState({},"",se),window.dispatchEvent(new HashChangeEvent("hashchange",{newURL:window.location.origin+window.location.pathname+se,oldURL:window.location.href}))})}if(Kn.default.isSupported()&&(e.closest(".copy")||V("content.code.copy")&&!e.closest(".no-copy"))){let d=Hn(a.id);s.push(d),V("content.tooltips")&&l.push(Xe(d,{viewport$}))}if(s.length){let d=Pn();d.append(...s),a.insertBefore(d,e)}return es(e).pipe(O(d=>n.next(d)),A(()=>n.complete()),m(d=>P({ref:e},d)),Ve(L(...l).pipe(W(i))))});return V("content.lazy")?mt(e).pipe(g(n=>n),Ee(1),b(()=>o)):o}function ts(e,{target$:t,print$:r}){let o=!0;return L(t.pipe(m(n=>n.closest("details:not([open])")),g(n=>e===n),m(()=>({action:"open",reveal:!0}))),r.pipe(g(n=>n||!o),O(()=>o=e.open),m(n=>({action:n?"open":"close"}))))}function Bn(e,t){return H(()=>{let r=new T;return r.subscribe(({action:o,reveal:n})=>{e.toggleAttribute("open",o==="open"),n&&e.scrollIntoView()}),ts(e,t).pipe(O(o=>r.next(o)),A(()=>r.complete()),m(o=>P({ref:e},o)))})}var Gn=0;function rs(e){let t=document.createElement("h3");t.innerHTML=e.innerHTML;let r=[t],o=e.nextElementSibling;for(;o&&!(o instanceof HTMLHeadingElement);)r.push(o),o=o.nextElementSibling;return r}function os(e,t){for(let r of M("[href], [src]",e))for(let o of["href","src"]){let n=r.getAttribute(o);if(n&&!/^(?:[a-z]+:)?\/\//i.test(n)){r[o]=new URL(r.getAttribute(o),t).toString();break}}for(let r of M("[name^=__], [for]",e))for(let o of["id","for","name"]){let n=r.getAttribute(o);n&&r.setAttribute(o,`${n}$preview_${Gn}`)}return Gn++,$(e)}function Jn(e,t){let{sitemap$:r}=t;if(!(e instanceof HTMLAnchorElement))return y;if(!(V("navigation.instant.preview")||e.hasAttribute("data-preview")))return y;e.removeAttribute("title");let o=z([Ye(e),it(e)]).pipe(m(([i,s])=>i||s),Y(),g(i=>i));return rt([r,o]).pipe(b(([i])=>{let s=new URL(e.href);return s.search=s.hash="",i.has(`${s}`)?$(s):y}),b(i=>xr(i).pipe(b(s=>os(s,i)))),b(i=>{let s=e.hash?`article [id="${e.hash.slice(1)}"]`:"article h1",a=ue(s,i);return typeof a=="undefined"?y:$(rs(a))})).pipe(b(i=>{let s=new F(a=>{let c=wr(...i);return a.next(c),document.body.append(c),()=>c.remove()});return Vt(e,P({content$:s},t))}))}var Xn=".node circle,.node ellipse,.node path,.node polygon,.node rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}marker{fill:var(--md-mermaid-edge-color)!important}.edgeLabel .label rect{fill:#0000}.flowchartTitleText{fill:var(--md-mermaid-label-fg-color)}.label{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.label foreignObject{line-height:normal;overflow:visible}.label div .edgeLabel{color:var(--md-mermaid-label-fg-color)}.edgeLabel,.edgeLabel p,.label div .edgeLabel{background-color:var(--md-mermaid-label-bg-color)}.edgeLabel,.edgeLabel p{fill:var(--md-mermaid-label-bg-color);color:var(--md-mermaid-edge-color)}.edgePath .path,.flowchart-link{stroke:var(--md-mermaid-edge-color)}.edgePath .arrowheadPath{fill:var(--md-mermaid-edge-color);stroke:none}.cluster rect{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}.cluster span{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}g #flowchart-circleEnd,g #flowchart-circleStart,g #flowchart-crossEnd,g #flowchart-crossStart,g #flowchart-pointEnd,g #flowchart-pointStart{stroke:none}.classDiagramTitleText{fill:var(--md-mermaid-label-fg-color)}g.classGroup line,g.classGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.classGroup text{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.classLabel .box{fill:var(--md-mermaid-label-bg-color);background-color:var(--md-mermaid-label-bg-color);opacity:1}.classLabel .label{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.node .divider{stroke:var(--md-mermaid-node-fg-color)}.relation{stroke:var(--md-mermaid-edge-color)}.cardinality{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.cardinality text{fill:inherit!important}defs marker.marker.composition.class path,defs marker.marker.dependency.class path,defs marker.marker.extension.class path{fill:var(--md-mermaid-edge-color)!important;stroke:var(--md-mermaid-edge-color)!important}defs marker.marker.aggregation.class path{fill:var(--md-mermaid-label-bg-color)!important;stroke:var(--md-mermaid-edge-color)!important}.statediagramTitleText{fill:var(--md-mermaid-label-fg-color)}g.stateGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.stateGroup .state-title{fill:var(--md-mermaid-label-fg-color)!important;font-family:var(--md-mermaid-font-family)}g.stateGroup .composit{fill:var(--md-mermaid-label-bg-color)}.nodeLabel,.nodeLabel p{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}a .nodeLabel{text-decoration:underline}.node circle.state-end,.node circle.state-start,.start-state{fill:var(--md-mermaid-edge-color);stroke:none}.end-state-inner,.end-state-outer{fill:var(--md-mermaid-edge-color)}.end-state-inner,.node circle.state-end{stroke:var(--md-mermaid-label-bg-color)}.transition{stroke:var(--md-mermaid-edge-color)}[id^=state-fork] rect,[id^=state-join] rect{fill:var(--md-mermaid-edge-color)!important;stroke:none!important}.statediagram-cluster.statediagram-cluster .inner{fill:var(--md-default-bg-color)}.statediagram-cluster rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.statediagram-state rect.divider{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}defs #statediagram-barbEnd{stroke:var(--md-mermaid-edge-color)}[id^=entity] path,[id^=entity] rect{fill:var(--md-default-bg-color)}.relationshipLine{stroke:var(--md-mermaid-edge-color)}defs .marker.oneOrMore.er *,defs .marker.onlyOne.er *,defs .marker.zeroOrMore.er *,defs .marker.zeroOrOne.er *{stroke:var(--md-mermaid-edge-color)!important}text:not([class]):last-child{fill:var(--md-mermaid-label-fg-color)}.actor{fill:var(--md-mermaid-sequence-actor-bg-color);stroke:var(--md-mermaid-sequence-actor-border-color)}text.actor>tspan{fill:var(--md-mermaid-sequence-actor-fg-color);font-family:var(--md-mermaid-font-family)}line{stroke:var(--md-mermaid-sequence-actor-line-color)}.actor-man circle,.actor-man line{fill:var(--md-mermaid-sequence-actorman-bg-color);stroke:var(--md-mermaid-sequence-actorman-line-color)}.messageLine0,.messageLine1{stroke:var(--md-mermaid-sequence-message-line-color)}.note{fill:var(--md-mermaid-sequence-note-bg-color);stroke:var(--md-mermaid-sequence-note-border-color)}.loopText,.loopText>tspan,.messageText,.noteText>tspan{stroke:none;font-family:var(--md-mermaid-font-family)!important}.messageText{fill:var(--md-mermaid-sequence-message-fg-color)}.loopText,.loopText>tspan{fill:var(--md-mermaid-sequence-loop-fg-color)}.noteText>tspan{fill:var(--md-mermaid-sequence-note-fg-color)}#arrowhead path{fill:var(--md-mermaid-sequence-message-line-color);stroke:none}.loopLine{fill:var(--md-mermaid-sequence-loop-bg-color);stroke:var(--md-mermaid-sequence-loop-border-color)}.labelBox{fill:var(--md-mermaid-sequence-label-bg-color);stroke:none}.labelText,.labelText>span{fill:var(--md-mermaid-sequence-label-fg-color);font-family:var(--md-mermaid-font-family)}.sequenceNumber{fill:var(--md-mermaid-sequence-number-fg-color)}rect.rect{fill:var(--md-mermaid-sequence-box-bg-color);stroke:none}rect.rect+text.text{fill:var(--md-mermaid-sequence-box-fg-color)}defs #sequencenumber{fill:var(--md-mermaid-sequence-number-bg-color)!important}";var so,is=0;function as(){return typeof mermaid=="undefined"||mermaid instanceof Element?_t("https://unpkg.com/mermaid@11/dist/mermaid.min.js"):$(void 0)}function Zn(e){return e.classList.remove("mermaid"),so||(so=as().pipe(O(()=>mermaid.initialize({startOnLoad:!1,themeCSS:Xn,sequence:{actorFontSize:"16px",messageFontSize:"16px",noteFontSize:"16px"}})),m(()=>{}),Z(1))),so.subscribe(()=>go(null,null,function*(){e.classList.add("mermaid");let t=`__mermaid_${is++}`,r=x("div",{class:"mermaid"}),o=e.textContent,{svg:n,fn:i}=yield mermaid.render(t,o),s=r.attachShadow({mode:"closed"});s.innerHTML=n,e.replaceWith(r),i==null||i(s)})),so.pipe(m(()=>({ref:e})))}var ei=x("table");function ti(e){return e.replaceWith(ei),ei.replaceWith(Un(e)),$({ref:e})}function ss(e){let t=e.find(r=>r.checked)||e[0];return L(...e.map(r=>h(r,"change").pipe(m(()=>j(`label[for="${r.id}"]`))))).pipe(Q(j(`label[for="${t.id}"]`)),m(r=>({active:r})))}function ri(e,{viewport$:t,target$:r}){let o=j(".tabbed-labels",e),n=M(":scope > input",e),i=no("prev");e.append(i);let s=no("next");return e.append(s),H(()=>{let a=new T,c=a.pipe(oe(),ae(!0));z([a,Le(e),mt(e)]).pipe(W(c),$e(1,ye)).subscribe({next([{active:p},l]){let f=Be(p),{width:u}=de(p);e.style.setProperty("--md-indicator-x",`${f.x}px`),e.style.setProperty("--md-indicator-width",`${u}px`);let d=gr(o);(f.xd.x+l.width)&&o.scrollTo({left:Math.max(0,f.x-16),behavior:"smooth"})},complete(){e.style.removeProperty("--md-indicator-x"),e.style.removeProperty("--md-indicator-width")}}),z([Ge(o),Le(o)]).pipe(W(c)).subscribe(([p,l])=>{let f=At(o);i.hidden=p.x<16,s.hidden=p.x>f.width-l.width-16}),L(h(i,"click").pipe(m(()=>-1)),h(s,"click").pipe(m(()=>1))).pipe(W(c)).subscribe(p=>{let{width:l}=de(o);o.scrollBy({left:l*p,behavior:"smooth"})}),r.pipe(W(c),g(p=>n.includes(p))).subscribe(p=>p.click()),o.classList.add("tabbed-labels--linked");for(let p of n){let l=j(`label[for="${p.id}"]`);l.replaceChildren(x("a",{href:`#${l.htmlFor}`,tabIndex:-1},...Array.from(l.childNodes))),h(l.firstElementChild,"click").pipe(W(c),g(f=>!(f.metaKey||f.ctrlKey)),O(f=>{f.preventDefault(),f.stopPropagation()})).subscribe(()=>{history.replaceState({},"",`#${l.htmlFor}`),l.click()})}return V("content.tabs.link")&&a.pipe(Ie(1),te(t)).subscribe(([{active:p},{offset:l}])=>{let f=p.innerText.trim();if(p.hasAttribute("data-md-switching"))p.removeAttribute("data-md-switching");else{let u=e.offsetTop-l.y;for(let v of M("[data-tabs]"))for(let S of M(":scope > input",v)){let X=j(`label[for="${S.id}"]`);if(X!==p&&X.innerText.trim()===f){X.setAttribute("data-md-switching",""),S.click();break}}window.scrollTo({top:e.offsetTop-u});let d=__md_get("__tabs")||[];__md_set("__tabs",[...new Set([f,...d])])}}),a.pipe(W(c)).subscribe(()=>{for(let p of M("audio, video",e))p.offsetWidth&&p.autoplay?p.play().catch(()=>{}):p.pause()}),ss(n).pipe(O(p=>a.next(p)),A(()=>a.complete()),m(p=>P({ref:e},p)))}).pipe(et(pe))}function oi(e,t){let{viewport$:r,target$:o,print$:n}=t;return L(...M(".annotate:not(.highlight)",e).map(i=>zn(i,{target$:o,print$:n})),...M("pre:not(.mermaid) > code",e).map(i=>Yn(i,{target$:o,print$:n})),...M("a",e).map(i=>Jn(i,t)),...M("pre.mermaid",e).map(i=>Zn(i)),...M("table:not([class])",e).map(i=>ti(i)),...M("details",e).map(i=>Bn(i,{target$:o,print$:n})),...M("[data-tabs]",e).map(i=>ri(i,{viewport$:r,target$:o})),...M("[title]:not([data-preview])",e).filter(()=>V("content.tooltips")).map(i=>Xe(i,{viewport$:r})),...M(".footnote-ref",e).filter(()=>V("content.footnote.tooltips")).map(i=>Vt(i,{content$:new F(s=>{let a=new URL(i.href).hash.slice(1),c=Array.from(document.getElementById(a).cloneNode(!0).children),p=wr(...c);return s.next(p),document.body.append(p),()=>p.remove()}),viewport$:r})))}function cs(e,{alert$:t}){return t.pipe(b(r=>L($(!0),$(!1).pipe(nt(2e3))).pipe(m(o=>({message:r,active:o})))))}function ni(e,t){let r=j(".md-typeset",e);return H(()=>{let o=new T;return o.subscribe(({message:n,active:i})=>{e.classList.toggle("md-dialog--active",i),r.textContent=n}),cs(e,t).pipe(O(n=>o.next(n)),A(()=>o.complete()),m(n=>P({ref:e},n)))})}var ps=0;function ls(e,t){document.body.append(e);let{width:r}=de(e);e.style.setProperty("--md-tooltip-width",`${r}px`),e.remove();let o=vr(t),n=typeof o!="undefined"?Ge(o):$({x:0,y:0}),i=L(Ye(t),it(t)).pipe(Y());return z([i,n]).pipe(m(([s,a])=>{let{x:c,y:p}=Be(t),l=de(t),f=t.closest("table");return f&&t.parentElement&&(c+=f.offsetLeft+t.parentElement.offsetLeft,p+=f.offsetTop+t.parentElement.offsetTop),{active:s,offset:{x:c-a.x+l.width/2-r/2,y:p-a.y+l.height+8}}}))}function ii(e){let t=e.title;if(!t.length)return y;let r=`__tooltip_${ps++}`,o=Dt(r,"inline"),n=j(".md-typeset",o);return n.innerHTML=t,H(()=>{let i=new T;return i.subscribe({next({offset:s}){o.style.setProperty("--md-tooltip-x",`${s.x}px`),o.style.setProperty("--md-tooltip-y",`${s.y}px`)},complete(){o.style.removeProperty("--md-tooltip-x"),o.style.removeProperty("--md-tooltip-y")}}),L(i.pipe(g(({active:s})=>s)),i.pipe(Ae(250),g(({active:s})=>!s))).subscribe({next({active:s}){s?(e.insertAdjacentElement("afterend",o),e.setAttribute("aria-describedby",r),e.removeAttribute("title")):(o.remove(),e.removeAttribute("aria-describedby"),e.setAttribute("title",t))},complete(){o.remove(),e.removeAttribute("aria-describedby"),e.setAttribute("title",t)}}),i.pipe($e(16,ye)).subscribe(({active:s})=>{o.classList.toggle("md-tooltip--active",s)}),i.pipe(gt(125,ye),g(()=>!!e.offsetParent),m(()=>e.offsetParent.getBoundingClientRect()),m(({x:s})=>s)).subscribe({next(s){s?o.style.setProperty("--md-tooltip-0",`${-s}px`):o.style.removeProperty("--md-tooltip-0")},complete(){o.style.removeProperty("--md-tooltip-0")}}),ls(o,e).pipe(O(s=>i.next(s)),A(()=>i.complete()),m(s=>P({ref:e},s)))}).pipe(et(pe))}function ms({viewport$:e}){if(!V("header.autohide"))return $(!1);let t=e.pipe(m(({offset:{y:n}})=>n),ot(2,1),m(([n,i])=>[nMath.abs(i-n.y)>100),m(([,[n]])=>n),Y()),o=Je("search");return z([e,o]).pipe(m(([{offset:n},i])=>n.y>400&&!i),Y(),b(n=>n?r:$(!1)),Q(!1))}function ai(e,t){return H(()=>z([Le(e),ms(t)])).pipe(m(([{height:r},o])=>({height:r,hidden:o})),Y((r,o)=>r.height===o.height&&r.hidden===o.hidden),Z(1))}function si(e,{header$:t,main$:r}){return H(()=>{let o=new T,n=o.pipe(oe(),ae(!0));o.pipe(ne("active"),Pe(t)).subscribe(([{active:s},{hidden:a}])=>{e.classList.toggle("md-header--shadow",s&&!a),e.hidden=a});let i=fe(M("[title]",e)).pipe(g(()=>V("content.tooltips")),J(s=>ii(s)));return r.subscribe(o),t.pipe(W(n),m(s=>P({ref:e},s)),Ve(i.pipe(W(n))))})}function fs(e,{viewport$:t,header$:r}){return Er(e,{viewport$:t,header$:r}).pipe(m(({offset:{y:o}})=>{let{height:n}=de(e);return{active:n>0&&o>=n}}),ne("active"))}function ci(e,t){return H(()=>{let r=new T;r.subscribe({next({active:n}){e.classList.toggle("md-header__title--active",n)},complete(){e.classList.remove("md-header__title--active")}});let o=ue(".md-content h1");return typeof o=="undefined"?y:fs(o,t).pipe(O(n=>r.next(n)),A(()=>r.complete()),m(n=>P({ref:e},n)))})}function pi(e,{viewport$:t,header$:r}){let o=r.pipe(m(({height:i})=>i),Y()),n=o.pipe(b(()=>Le(e).pipe(m(({height:i})=>({top:e.offsetTop,bottom:e.offsetTop+i})),ne("bottom"))));return z([o,n,t]).pipe(m(([i,{top:s,bottom:a},{offset:{y:c},size:{height:p}}])=>(p=Math.max(0,p-Math.max(0,s-c,i)-Math.max(0,p+c-a)),{offset:s-i,height:p,active:s-i<=c})),Y((i,s)=>i.offset===s.offset&&i.height===s.height&&i.active===s.active))}function us(e){let t=__md_get("__palette")||{index:e.findIndex(o=>matchMedia(o.getAttribute("data-md-color-media")).matches)},r=Math.max(0,Math.min(t.index,e.length-1));return $(...e).pipe(J(o=>h(o,"change").pipe(m(()=>o))),Q(e[r]),m(o=>({index:e.indexOf(o),color:{media:o.getAttribute("data-md-color-media"),scheme:o.getAttribute("data-md-color-scheme"),primary:o.getAttribute("data-md-color-primary"),accent:o.getAttribute("data-md-color-accent")}})),Z(1))}function li(e){let t=M("input",e),r=x("meta",{name:"theme-color"});document.head.appendChild(r);let o=x("meta",{name:"color-scheme"});document.head.appendChild(o);let n=Wt("(prefers-color-scheme: light)");return H(()=>{let i=new T;return i.subscribe(s=>{if(document.body.setAttribute("data-md-color-switching",""),s.color.media==="(prefers-color-scheme)"){let a=matchMedia("(prefers-color-scheme: light)"),c=document.querySelector(a.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");s.color.scheme=c.getAttribute("data-md-color-scheme"),s.color.primary=c.getAttribute("data-md-color-primary"),s.color.accent=c.getAttribute("data-md-color-accent")}for(let[a,c]of Object.entries(s.color))document.body.setAttribute(`data-md-color-${a}`,c);for(let a=0;as.key==="Enter"),te(i,(s,a)=>a)).subscribe(({index:s})=>{s=(s+1)%t.length,t[s].click(),t[s].focus()}),i.pipe(m(()=>{let s=Ce("header"),a=window.getComputedStyle(s);return o.content=a.colorScheme,a.backgroundColor.match(/\d+/g).map(c=>(+c).toString(16).padStart(2,"0")).join("")})).subscribe(s=>r.content=`#${s}`),i.pipe(xe(pe)).subscribe(()=>{document.body.removeAttribute("data-md-color-switching")}),us(t).pipe(W(n.pipe(Ie(1))),vt(),O(s=>i.next(s)),A(()=>i.complete()),m(s=>P({ref:e},s)))})}function mi(e,{progress$:t}){return H(()=>{let r=new T;return r.subscribe(({value:o})=>{e.style.setProperty("--md-progress-value",`${o}`)}),t.pipe(O(o=>r.next({value:o})),A(()=>r.complete()),m(o=>({ref:e,value:o})))})}function fi(e,t){return e.protocol=t.protocol,e.hostname=t.hostname,e}function ds(e,t){let r=new Map;for(let o of M("url",e)){let n=j("loc",o),i=[fi(new URL(n.textContent),t)];r.set(`${i[0]}`,i);for(let s of M("[rel=alternate]",o)){let a=s.getAttribute("href");a!=null&&i.push(fi(new URL(a),t))}}return r}function kt(e){return En(new URL("sitemap.xml",e)).pipe(m(t=>ds(t,new URL(e))),ve(()=>$(new Map)),le())}function ui({document$:e}){let t=new Map;e.pipe(b(()=>M("link[rel=alternate]")),m(r=>new URL(r.href)),g(r=>!t.has(r.toString())),J(r=>kt(r).pipe(m(o=>[r,o]),ve(()=>y)))).subscribe(([r,o])=>{t.set(r.toString().replace(/\/$/,""),o)}),h(document.body,"click").pipe(g(r=>!r.metaKey&&!r.ctrlKey),b(r=>{if(r.target instanceof Element){let o=r.target.closest("a");if(o&&!o.target){let n=[...t].find(([f])=>o.href.startsWith(`${f}/`));if(typeof n=="undefined")return y;let[i,s]=n,a=we();if(a.href.startsWith(i))return y;let c=Te(),p=a.href.replace(c.base,"");p=`${i}/${p}`;let l=s.has(p.split("#")[0])?new URL(p,c.base):new URL(i);return r.preventDefault(),$(l)}}return y})).subscribe(r=>st(r,!0))}var co=$t(ao());function hs(e){e.setAttribute("data-md-copying","");let t=e.closest("[data-copy]"),r=t?t.getAttribute("data-copy"):e.innerText;return e.removeAttribute("data-md-copying"),r.trimEnd()}function di({alert$:e}){co.default.isSupported()&&new F(t=>{new co.default("[data-clipboard-target], [data-clipboard-text]",{text:r=>r.getAttribute("data-clipboard-text")||hs(j(r.getAttribute("data-clipboard-target")))}).on("success",r=>t.next(r))}).pipe(O(t=>{t.trigger.focus()}),m(()=>Me("clipboard.copied"))).subscribe(e)}function hi(e,t){if(!(e.target instanceof Element))return y;let r=e.target.closest("a");if(r===null)return y;if(r.target||e.metaKey||e.ctrlKey)return y;let o=new URL(r.href);return o.search=o.hash="",t.has(`${o}`)?(e.preventDefault(),$(r)):y}function bi(e){let t=new Map;for(let r of M(":scope > *",e.head))t.set(r.outerHTML,r);return t}function vi(e){for(let t of M("[href], [src]",e))for(let r of["href","src"]){let o=t.getAttribute(r);if(o&&!/^(?:[a-z]+:)?\/\//i.test(o)){t[r]=t[r];break}}return $(e)}function bs(e){for(let o of["[data-md-component=announce]","[data-md-component=container]","[data-md-component=header-topic]","[data-md-component=outdated]","[data-md-component=logo]","[data-md-component=skip]",...V("navigation.tabs.sticky")?["[data-md-component=tabs]"]:[]]){let n=ue(o),i=ue(o,e);typeof n!="undefined"&&typeof i!="undefined"&&n.replaceWith(i)}let t=bi(document);for(let[o,n]of bi(e))t.has(o)?t.delete(o):document.head.appendChild(n);for(let o of t.values()){let n=o.getAttribute("name");n!=="theme-color"&&n!=="color-scheme"&&o.remove()}let r=Ce("container");return Ke(M("script",r)).pipe(b(o=>{let n=e.createElement("script");if(o.src){for(let i of o.getAttributeNames())n.setAttribute(i,o.getAttribute(i));return o.replaceWith(n),new F(i=>{n.onload=()=>i.complete()})}else return n.textContent=o.textContent,o.replaceWith(n),y}),oe(),ae(document))}function gi({sitemap$:e,location$:t,viewport$:r,progress$:o}){if(location.protocol==="file:")return y;$(document).subscribe(vi);let n=h(document.body,"click").pipe(Pe(e),b(([a,c])=>hi(a,c)),m(({href:a})=>new URL(a)),le()),i=h(window,"popstate").pipe(m(we),le());n.pipe(te(r)).subscribe(([a,{offset:c}])=>{history.replaceState(c,""),history.pushState(null,"",a)}),L(n,i).subscribe(t);let s=t.pipe(ne("pathname"),b(a=>xr(a,{progress$:o}).pipe(ve(()=>(st(a,!0),y)))),b(vi),b(bs),le());return L(s.pipe(te(t,(a,c)=>c)),s.pipe(b(()=>t),ne("hash")),t.pipe(Y((a,c)=>a.pathname===c.pathname&&a.hash===c.hash),b(()=>n),O(()=>history.back()))).subscribe(a=>{var c,p;history.state!==null||!a.hash?window.scrollTo(0,(p=(c=history.state)==null?void 0:c.y)!=null?p:0):(history.scrollRestoration="auto",gn(a.hash),history.scrollRestoration="manual")}),t.subscribe(()=>{history.scrollRestoration="manual"}),h(window,"beforeunload").subscribe(()=>{history.scrollRestoration="auto"}),r.pipe(ne("offset"),Ae(100)).subscribe(({offset:a})=>{history.replaceState(a,"")}),V("navigation.instant.prefetch")&&L(h(document.body,"mousemove"),h(document.body,"focusin")).pipe(Pe(e),b(([a,c])=>hi(a,c)),Ae(25),Qr(({href:a})=>a),hr(a=>{let c=document.createElement("link");return c.rel="prefetch",c.href=a.toString(),document.head.appendChild(c),h(c,"load").pipe(m(()=>c),Ee(1))})).subscribe(a=>a.remove()),s}var yi=$t(ro());function xi(e){let t=e.separator.split("|").map(n=>n.replace(/(\(\?[!=<][^)]+\))/g,"").length===0?"\uFFFD":n).join("|"),r=new RegExp(t,"img"),o=(n,i,s)=>`${i}${s}`;return n=>{n=n.replace(/[\s*+\-:~^]+/g," ").replace(/&/g,"&").trim();let i=new RegExp(`(^|${e.separator}|)(${n.replace(/[|\\{}()[\]^$+*?.-]/g,"\\$&").replace(r,"|")})`,"img");return s=>(0,yi.default)(s).replace(i,o).replace(/<\/mark>(\s+)]*>/img,"$1")}}function zt(e){return e.type===1}function Sr(e){return e.type===3}function Ei(e,t){let r=Mn(e);return L($(location.protocol!=="file:"),Je("search")).pipe(Re(o=>o),b(()=>t)).subscribe(({config:o,docs:n})=>r.next({type:0,data:{config:o,docs:n,options:{suggest:V("search.suggest")}}})),r}function wi(e){var l;let{selectedVersionSitemap:t,selectedVersionBaseURL:r,currentLocation:o,currentBaseURL:n}=e,i=(l=po(n))==null?void 0:l.pathname;if(i===void 0)return;let s=ys(o.pathname,i);if(s===void 0)return;let a=Es(t.keys());if(!t.has(a))return;let c=po(s,a);if(!c||!t.has(c.href))return;let p=po(s,r);if(p)return p.hash=o.hash,p.search=o.search,p}function po(e,t){try{return new URL(e,t)}catch(r){return}}function ys(e,t){if(e.startsWith(t))return e.slice(t.length)}function xs(e,t){let r=Math.min(e.length,t.length),o;for(o=0;oy)),o=r.pipe(m(n=>{let[,i]=t.base.match(/([^/]+)\/?$/);return n.find(({version:s,aliases:a})=>s===i||a.includes(i))||n[0]}));r.pipe(m(n=>new Map(n.map(i=>[`${new URL(`../${i.version}/`,t.base)}`,i]))),b(n=>h(document.body,"click").pipe(g(i=>!i.metaKey&&!i.ctrlKey),te(o),b(([i,s])=>{if(i.target instanceof Element){let a=i.target.closest("a");if(a&&!a.target&&n.has(a.href)){let c=a.href;return!i.target.closest(".md-version")&&n.get(c)===s?y:(i.preventDefault(),$(new URL(c)))}}return y}),b(i=>kt(i).pipe(m(s=>{var a;return(a=wi({selectedVersionSitemap:s,selectedVersionBaseURL:i,currentLocation:we(),currentBaseURL:t.base}))!=null?a:i})))))).subscribe(n=>st(n,!0)),z([r,o]).subscribe(([n,i])=>{j(".md-header__topic").appendChild(Wn(n,i))}),e.pipe(b(()=>o)).subscribe(n=>{var a;let i=new URL(t.base),s=__md_get("__outdated",sessionStorage,i);if(s===null){s=!0;let c=((a=t.version)==null?void 0:a.default)||"latest";Array.isArray(c)||(c=[c]);e:for(let p of c)for(let l of n.aliases.concat(n.version))if(new RegExp(p,"i").test(l)){s=!1;break e}__md_set("__outdated",s,sessionStorage,i)}if(s)for(let c of me("outdated"))c.hidden=!1})}function ws(e,{worker$:t}){let{searchParams:r}=we();r.has("q")&&(at("search",!0),e.value=r.get("q"),e.focus(),Je("search").pipe(Re(i=>!i)).subscribe(()=>{let i=we();i.searchParams.delete("q"),history.replaceState({},"",`${i}`)}));let o=Ye(e),n=L(t.pipe(Re(zt)),h(e,"keyup"),o).pipe(m(()=>e.value),Y());return z([n,o]).pipe(m(([i,s])=>({value:i,focus:s})),Z(1))}function Si(e,{worker$:t}){let r=new T,o=r.pipe(oe(),ae(!0));z([t.pipe(Re(zt)),r],(i,s)=>s).pipe(ne("value")).subscribe(({value:i})=>t.next({type:2,data:i})),r.pipe(ne("focus")).subscribe(({focus:i})=>{i&&at("search",i)}),h(e.form,"reset").pipe(W(o)).subscribe(()=>e.focus());let n=j("header [for=__search]");return h(n,"click").subscribe(()=>e.focus()),ws(e,{worker$:t}).pipe(O(i=>r.next(i)),A(()=>r.complete()),m(i=>P({ref:e},i)),Z(1))}function Oi(e,{worker$:t,query$:r}){let o=new T,n=un(e.parentElement).pipe(g(Boolean)),i=e.parentElement,s=j(":scope > :first-child",e),a=j(":scope > :last-child",e);Je("search").subscribe(l=>{a.setAttribute("role",l?"list":"presentation"),a.hidden=!l}),o.pipe(te(r),Gr(t.pipe(Re(zt)))).subscribe(([{items:l},{value:f}])=>{switch(l.length){case 0:s.textContent=f.length?Me("search.result.none"):Me("search.result.placeholder");break;case 1:s.textContent=Me("search.result.one");break;default:let u=br(l.length);s.textContent=Me("search.result.other",u)}});let c=o.pipe(O(()=>a.innerHTML=""),b(({items:l})=>L($(...l.slice(0,10)),$(...l.slice(10)).pipe(ot(4),Xr(n),b(([f])=>f)))),m(Fn),le());return c.subscribe(l=>a.appendChild(l)),c.pipe(J(l=>{let f=ue("details",l);return typeof f=="undefined"?y:h(f,"toggle").pipe(W(o),m(()=>f))})).subscribe(l=>{l.open===!1&&l.offsetTop<=i.scrollTop&&i.scrollTo({top:l.offsetTop})}),t.pipe(g(Sr),m(({data:l})=>l)).pipe(O(l=>o.next(l)),A(()=>o.complete()),m(l=>P({ref:e},l)))}function Ts(e,{query$:t}){return t.pipe(m(({value:r})=>{let o=we();return o.hash="",r=r.replace(/\s+/g,"+").replace(/&/g,"%26").replace(/=/g,"%3D"),o.search=`q=${r}`,{url:o}}))}function Li(e,t){let r=new T,o=r.pipe(oe(),ae(!0));return r.subscribe(({url:n})=>{e.setAttribute("data-clipboard-text",e.href),e.href=`${n}`}),h(e,"click").pipe(W(o)).subscribe(n=>n.preventDefault()),Ts(e,t).pipe(O(n=>r.next(n)),A(()=>r.complete()),m(n=>P({ref:e},n)))}function Mi(e,{worker$:t,keyboard$:r}){let o=new T,n=Ce("search-query"),i=L(h(n,"keydown"),h(n,"focus")).pipe(xe(pe),m(()=>n.value),Y());return o.pipe(Pe(i),m(([{suggest:a},c])=>{let p=c.split(/([\s-]+)/);if(a!=null&&a.length&&p[p.length-1]){let l=a[a.length-1];l.startsWith(p[p.length-1])&&(p[p.length-1]=l)}else p.length=0;return p})).subscribe(a=>e.innerHTML=a.join("").replace(/\s/g," ")),r.pipe(g(({mode:a})=>a==="search")).subscribe(a=>{a.type==="ArrowRight"&&e.innerText.length&&n.selectionStart===n.value.length&&(n.value=e.innerText)}),t.pipe(g(Sr),m(({data:a})=>a)).pipe(O(a=>o.next(a)),A(()=>o.complete()),m(()=>({ref:e})))}function _i(e,{index$:t,keyboard$:r}){let o=Te();try{let n=Ei(o.search,t),i=Ce("search-query",e),s=Ce("search-result",e);h(e,"click").pipe(g(({target:c})=>c instanceof Element&&!!c.closest("a"))).subscribe(()=>at("search",!1)),r.pipe(g(({mode:c})=>c==="search")).subscribe(c=>{let p=Ne();switch(c.type){case"Enter":if(p===i){let l=new Map;for(let f of M(":first-child [href]",s)){let u=f.firstElementChild;l.set(f,parseFloat(u.getAttribute("data-md-score")))}if(l.size){let[[f]]=[...l].sort(([,u],[,d])=>d-u);f.click()}c.claim()}break;case"Escape":case"Tab":at("search",!1),i.blur();break;case"ArrowUp":case"ArrowDown":if(typeof p=="undefined")i.focus();else{let l=[i,...M(":not(details) > [href], summary, details[open] [href]",s)],f=Math.max(0,(Math.max(0,l.indexOf(p))+l.length+(c.type==="ArrowUp"?-1:1))%l.length);l[f].focus()}c.claim();break;default:i!==Ne()&&i.focus()}}),r.pipe(g(({mode:c})=>c==="global")).subscribe(c=>{switch(c.type){case"f":case"s":case"/":i.focus(),i.select(),c.claim();break}});let a=Si(i,{worker$:n});return L(a,Oi(s,{worker$:n,query$:a})).pipe(Ve(...me("search-share",e).map(c=>Li(c,{query$:a})),...me("search-suggest",e).map(c=>Mi(c,{worker$:n,keyboard$:r}))))}catch(n){return e.hidden=!0,tt}}function Ai(e,{index$:t,location$:r}){return z([t,r.pipe(Q(we()),g(o=>!!o.searchParams.get("h")))]).pipe(m(([o,n])=>xi(o.config)(n.searchParams.get("h"))),m(o=>{var s;let n=new Map,i=document.createNodeIterator(e,NodeFilter.SHOW_TEXT);for(let a=i.nextNode();a;a=i.nextNode())if((s=a.parentElement)!=null&&s.offsetHeight){let c=a.textContent,p=o(c);p.length>c.length&&n.set(a,p)}for(let[a,c]of n){let{childNodes:p}=x("span",null,c);a.replaceWith(...Array.from(p))}return{ref:e,nodes:n}}))}function Ss(e,{viewport$:t,main$:r}){let o=e.closest(".md-grid"),n=o.offsetTop-o.parentElement.offsetTop;return z([r,t]).pipe(m(([{offset:i,height:s},{offset:{y:a}}])=>(s=s+Math.min(n,Math.max(0,a-i))-n,{height:s,locked:a>=i+n})),Y((i,s)=>i.height===s.height&&i.locked===s.locked))}function lo(e,o){var n=o,{header$:t}=n,r=vo(n,["header$"]);let i=j(".md-sidebar__scrollwrap",e),{y:s}=Be(i);return H(()=>{let a=new T,c=a.pipe(oe(),ae(!0)),p=a.pipe($e(0,ye));return p.pipe(te(t)).subscribe({next([{height:l},{height:f}]){i.style.height=`${l-2*s}px`,e.style.top=`${f}px`},complete(){i.style.height="",e.style.top=""}}),p.pipe(Re()).subscribe(()=>{for(let l of M(".md-nav__link--active[href]",e)){if(!l.clientHeight)continue;let f=l.closest(".md-sidebar__scrollwrap");if(typeof f!="undefined"){let u=l.offsetTop-f.offsetTop,{height:d}=de(f);f.scrollTo({top:u-d/2})}}}),fe(M("label[tabindex]",e)).pipe(J(l=>h(l,"click").pipe(xe(pe),m(()=>l),W(c)))).subscribe(l=>{let f=j(`[id="${l.htmlFor}"]`);j(`[aria-labelledby="${l.id}"]`).setAttribute("aria-expanded",`${f.checked}`)}),V("content.tooltips")&&fe(M("abbr[title]",e)).pipe(J(l=>Xe(l,{viewport$})),W(c)).subscribe(),Ss(e,r).pipe(O(l=>a.next(l)),A(()=>a.complete()),m(l=>P({ref:e},l)))})}function Ci(e,t){if(typeof t!="undefined"){let r=`https://api.github.com/repos/${e}/${t}`;return rt(ze(`${r}/releases/latest`).pipe(ve(()=>y),m(o=>({version:o.tag_name})),Qe({})),ze(r).pipe(ve(()=>y),m(o=>({stars:o.stargazers_count,forks:o.forks_count})),Qe({}))).pipe(m(([o,n])=>P(P({},o),n)))}else{let r=`https://api.github.com/users/${e}`;return ze(r).pipe(m(o=>({repositories:o.public_repos})),Qe({}))}}function ki(e,t){let r=`https://${e}/api/v4/projects/${encodeURIComponent(t)}`;return rt(ze(`${r}/releases/permalink/latest`).pipe(ve(()=>y),m(({tag_name:o})=>({version:o})),Qe({})),ze(r).pipe(ve(()=>y),m(({star_count:o,forks_count:n})=>({stars:o,forks:n})),Qe({}))).pipe(m(([o,n])=>P(P({},o),n)))}function Hi(e){let t=e.match(/^.+github\.com\/([^/]+)\/?([^/]+)?/i);if(t){let[,r,o]=t;return Ci(r,o)}if(t=e.match(/^.+?([^/]*gitlab[^/]+)\/(.+?)\/?$/i),t){let[,r,o]=t;return ki(r,o)}return y}var Os;function Ls(e){return Os||(Os=H(()=>{let t=__md_get("__source",sessionStorage);if(t)return $(t);if(me("consent").length){let o=__md_get("__consent");if(!(o&&o.github))return y}return Hi(e.href).pipe(O(o=>__md_set("__source",o,sessionStorage)))}).pipe(ve(()=>y),g(t=>Object.keys(t).length>0),m(t=>({facts:t})),Z(1)))}function $i(e){let t=j(":scope > :last-child",e);return H(()=>{let r=new T;return r.subscribe(({facts:o})=>{t.appendChild(jn(o)),t.classList.add("md-source__repository--active")}),Ls(e).pipe(O(o=>r.next(o)),A(()=>r.complete()),m(o=>P({ref:e},o)))})}function Ms(e,{viewport$:t,header$:r}){return Le(document.body).pipe(b(()=>Er(e,{header$:r,viewport$:t})),m(({offset:{y:o}})=>({hidden:o>=10})),ne("hidden"))}function Pi(e,t){return H(()=>{let r=new T;return r.subscribe({next({hidden:o}){e.hidden=o},complete(){e.hidden=!1}}),(V("navigation.tabs.sticky")?$({hidden:!1}):Ms(e,t)).pipe(O(o=>r.next(o)),A(()=>r.complete()),m(o=>P({ref:e},o)))})}function _s(e,{viewport$:t,header$:r}){let o=new Map,n=M(".md-nav__link",e);for(let a of n){let c=decodeURIComponent(a.hash.substring(1)),p=ue(`[id="${c}"]`);typeof p!="undefined"&&o.set(a,p)}let i=r.pipe(ne("height"),m(({height:a})=>{let c=Ce("main"),p=j(":scope > :first-child",c);return a+.8*(p.offsetTop-c.offsetTop)}),le());return Le(document.body).pipe(ne("height"),b(a=>H(()=>{let c=[];return $([...o].reduce((p,[l,f])=>{for(;c.length&&o.get(c[c.length-1]).tagName>=f.tagName;)c.pop();let u=f.offsetTop;for(;!u&&f.parentElement;)f=f.parentElement,u=f.offsetTop;let d=f.offsetParent;for(;d;d=d.offsetParent)u+=d.offsetTop;return p.set([...c=[...c,l]].reverse(),u)},new Map))}).pipe(m(c=>new Map([...c].sort(([,p],[,l])=>p-l))),Pe(i),b(([c,p])=>t.pipe(Ut(([l,f],{offset:{y:u},size:d})=>{let v=u+d.height>=Math.floor(a.height);for(;f.length;){let[,S]=f[0];if(S-p=u&&!v)f=[l.pop(),...f];else break}return[l,f]},[[],[...c]]),Y((l,f)=>l[0]===f[0]&&l[1]===f[1])))))).pipe(m(([a,c])=>({prev:a.map(([p])=>p),next:c.map(([p])=>p)})),Q({prev:[],next:[]}),ot(2,1),m(([a,c])=>a.prev.length{let i=new T,s=i.pipe(oe(),ae(!0));if(i.subscribe(({prev:a,next:c})=>{for(let[p]of c)p.classList.remove("md-nav__link--passed"),p.classList.remove("md-nav__link--active");for(let[p,[l]]of a.entries())l.classList.add("md-nav__link--passed"),l.classList.toggle("md-nav__link--active",p===a.length-1)}),V("toc.follow")){let a=L(t.pipe(Ae(1),m(()=>{})),t.pipe(Ae(250),m(()=>"smooth")));i.pipe(g(({prev:c})=>c.length>0),Pe(o.pipe(xe(pe))),te(a)).subscribe(([[{prev:c}],p])=>{let[l]=c[c.length-1];if(l.offsetHeight){let f=vr(l);if(typeof f!="undefined"){let u=l.offsetTop-f.offsetTop,{height:d}=de(f);f.scrollTo({top:u-d/2,behavior:p})}}})}return V("navigation.tracking")&&t.pipe(W(s),ne("offset"),Ae(250),Ie(1),W(n.pipe(Ie(1))),vt({delay:250}),te(i)).subscribe(([,{prev:a}])=>{let c=we(),p=a[a.length-1];if(p&&p.length){let[l]=p,{hash:f}=new URL(l.href);c.hash!==f&&(c.hash=f,history.replaceState({},"",`${c}`))}else c.hash="",history.replaceState({},"",`${c}`)}),_s(e,{viewport$:t,header$:r}).pipe(O(a=>i.next(a)),A(()=>i.complete()),m(a=>P({ref:e},a)))})}function As(e,{viewport$:t,main$:r,target$:o}){let n=t.pipe(m(({offset:{y:s}})=>s),ot(2,1),m(([s,a])=>s>a&&a>0),Y()),i=r.pipe(m(({active:s})=>s));return z([i,n]).pipe(m(([s,a])=>!(s&&a)),Y(),W(o.pipe(Ie(1))),ae(!0),vt({delay:250}),m(s=>({hidden:s})))}function Ii(e,{viewport$:t,header$:r,main$:o,target$:n}){let i=new T,s=i.pipe(oe(),ae(!0));return i.subscribe({next({hidden:a}){e.hidden=a,a?(e.setAttribute("tabindex","-1"),e.blur()):e.removeAttribute("tabindex")},complete(){e.style.top="",e.hidden=!0,e.removeAttribute("tabindex")}}),r.pipe(W(s),ne("height")).subscribe(({height:a})=>{e.style.top=`${a+16}px`}),h(e,"click").subscribe(a=>{a.preventDefault(),window.scrollTo({top:0})}),As(e,{viewport$:t,main$:o,target$:n}).pipe(O(a=>i.next(a)),A(()=>i.complete()),m(a=>P({ref:e},a)))}function Fi({document$:e,viewport$:t}){e.pipe(b(()=>M(".md-ellipsis")),J(r=>mt(r).pipe(W(e.pipe(Ie(1))),g(o=>o),m(()=>r),Ee(1))),g(r=>r.offsetWidth{let o=r.innerText,n=r.closest("a")||r;return n.title=o,V("content.tooltips")?Xe(n,{viewport$:t}).pipe(W(e.pipe(Ie(1))),A(()=>n.removeAttribute("title"))):y})).subscribe(),V("content.tooltips")&&e.pipe(b(()=>M(".md-status")),J(r=>Xe(r,{viewport$:t}))).subscribe()}function ji({document$:e,tablet$:t}){e.pipe(b(()=>M(".md-toggle--indeterminate")),O(r=>{r.indeterminate=!0,r.checked=!1}),J(r=>h(r,"change").pipe(Jr(()=>r.classList.contains("md-toggle--indeterminate")),m(()=>r))),te(t)).subscribe(([r,o])=>{r.classList.remove("md-toggle--indeterminate"),o&&(r.checked=!1)})}function Cs(){return/(iPad|iPhone|iPod)/.test(navigator.userAgent)}function Ui({document$:e}){e.pipe(b(()=>M("[data-md-scrollfix]")),O(t=>t.removeAttribute("data-md-scrollfix")),g(Cs),J(t=>h(t,"touchstart").pipe(m(()=>t)))).subscribe(t=>{let r=t.scrollTop;r===0?t.scrollTop=1:r+t.offsetHeight===t.scrollHeight&&(t.scrollTop=r-1)})}function Wi({viewport$:e,tablet$:t}){z([Je("search"),t]).pipe(m(([r,o])=>r&&!o),b(r=>$(r).pipe(nt(r?400:100))),te(e)).subscribe(([r,{offset:{y:o}}])=>{if(r)document.body.setAttribute("data-md-scrolllock",""),document.body.style.top=`-${o}px`;else{let n=-1*parseInt(document.body.style.top,10);document.body.removeAttribute("data-md-scrolllock"),document.body.style.top="",n&&window.scrollTo(0,n)}})}Object.entries||(Object.entries=function(e){let t=[];for(let r of Object.keys(e))t.push([r,e[r]]);return t});Object.values||(Object.values=function(e){let t=[];for(let r of Object.keys(e))t.push(e[r]);return t});typeof Element!="undefined"&&(Element.prototype.scrollTo||(Element.prototype.scrollTo=function(e,t){typeof e=="object"?(this.scrollLeft=e.left,this.scrollTop=e.top):(this.scrollLeft=e,this.scrollTop=t)}),Element.prototype.replaceWith||(Element.prototype.replaceWith=function(...e){let t=this.parentNode;if(t){e.length===0&&t.removeChild(this);for(let r=e.length-1;r>=0;r--){let o=e[r];typeof o=="string"?o=document.createTextNode(o):o.parentNode&&o.parentNode.removeChild(o),r?t.insertBefore(this.previousSibling,o):t.replaceChild(o,this)}}}));function ks(){return location.protocol==="file:"?_t(`${new URL("search/search_index.js",Or.base)}`).pipe(m(()=>__index),Z(1)):ze(new URL("search/search_index.json",Or.base))}document.documentElement.classList.remove("no-js");document.documentElement.classList.add("js");var ct=an(),Kt=bn(),Ht=yn(Kt),mo=hn(),ke=Ln(),Lr=Wt("(min-width: 60em)"),Vi=Wt("(min-width: 76.25em)"),Ni=xn(),Or=Te(),zi=document.forms.namedItem("search")?ks():tt,fo=new T;di({alert$:fo});ui({document$:ct});var uo=new T,qi=kt(Or.base);V("navigation.instant")&&gi({sitemap$:qi,location$:Kt,viewport$:ke,progress$:uo}).subscribe(ct);var Di;((Di=Or.version)==null?void 0:Di.provider)==="mike"&&Ti({document$:ct});L(Kt,Ht).pipe(nt(125)).subscribe(()=>{at("drawer",!1),at("search",!1)});mo.pipe(g(({mode:e})=>e==="global")).subscribe(e=>{switch(e.type){case"p":case",":let t=ue("link[rel=prev]");typeof t!="undefined"&&st(t);break;case"n":case".":let r=ue("link[rel=next]");typeof r!="undefined"&&st(r);break;case"Enter":let o=Ne();o instanceof HTMLLabelElement&&o.click()}});Fi({viewport$:ke,document$:ct});ji({document$:ct,tablet$:Lr});Ui({document$:ct});Wi({viewport$:ke,tablet$:Lr});var ft=ai(Ce("header"),{viewport$:ke}),qt=ct.pipe(m(()=>Ce("main")),b(e=>pi(e,{viewport$:ke,header$:ft})),Z(1)),Hs=L(...me("consent").map(e=>An(e,{target$:Ht})),...me("dialog").map(e=>ni(e,{alert$:fo})),...me("palette").map(e=>li(e)),...me("progress").map(e=>mi(e,{progress$:uo})),...me("search").map(e=>_i(e,{index$:zi,keyboard$:mo})),...me("source").map(e=>$i(e))),$s=H(()=>L(...me("announce").map(e=>_n(e)),...me("content").map(e=>oi(e,{sitemap$:qi,viewport$:ke,target$:Ht,print$:Ni})),...me("content").map(e=>V("search.highlight")?Ai(e,{index$:zi,location$:Kt}):y),...me("header").map(e=>si(e,{viewport$:ke,header$:ft,main$:qt})),...me("header-title").map(e=>ci(e,{viewport$:ke,header$:ft})),...me("sidebar").map(e=>e.getAttribute("data-md-type")==="navigation"?eo(Vi,()=>lo(e,{viewport$:ke,header$:ft,main$:qt})):eo(Lr,()=>lo(e,{viewport$:ke,header$:ft,main$:qt}))),...me("tabs").map(e=>Pi(e,{viewport$:ke,header$:ft})),...me("toc").map(e=>Ri(e,{viewport$:ke,header$:ft,main$:qt,target$:Ht})),...me("top").map(e=>Ii(e,{viewport$:ke,header$:ft,main$:qt,target$:Ht})))),Ki=ct.pipe(b(()=>$s),Ve(Hs),Z(1));Ki.subscribe();window.document$=ct;window.location$=Kt;window.target$=Ht;window.keyboard$=mo;window.viewport$=ke;window.tablet$=Lr;window.screen$=Vi;window.print$=Ni;window.alert$=fo;window.progress$=uo;window.component$=Ki;})(); +//# sourceMappingURL=bundle.79ae519e.min.js.map + diff --git a/site/assets/javascripts/bundle.79ae519e.min.js.map b/site/assets/javascripts/bundle.79ae519e.min.js.map new file mode 100644 index 000000000..5cf02892c --- /dev/null +++ b/site/assets/javascripts/bundle.79ae519e.min.js.map @@ -0,0 +1,7 @@ +{ + "version": 3, + "sources": ["node_modules/focus-visible/dist/focus-visible.js", "node_modules/escape-html/index.js", "node_modules/clipboard/dist/clipboard.js", "src/templates/assets/javascripts/bundle.ts", "node_modules/tslib/tslib.es6.mjs", "node_modules/rxjs/src/internal/util/isFunction.ts", "node_modules/rxjs/src/internal/util/createErrorClass.ts", "node_modules/rxjs/src/internal/util/UnsubscriptionError.ts", "node_modules/rxjs/src/internal/util/arrRemove.ts", "node_modules/rxjs/src/internal/Subscription.ts", "node_modules/rxjs/src/internal/config.ts", "node_modules/rxjs/src/internal/scheduler/timeoutProvider.ts", "node_modules/rxjs/src/internal/util/reportUnhandledError.ts", "node_modules/rxjs/src/internal/util/noop.ts", "node_modules/rxjs/src/internal/NotificationFactories.ts", "node_modules/rxjs/src/internal/util/errorContext.ts", "node_modules/rxjs/src/internal/Subscriber.ts", "node_modules/rxjs/src/internal/symbol/observable.ts", "node_modules/rxjs/src/internal/util/identity.ts", "node_modules/rxjs/src/internal/util/pipe.ts", "node_modules/rxjs/src/internal/Observable.ts", "node_modules/rxjs/src/internal/util/lift.ts", "node_modules/rxjs/src/internal/operators/OperatorSubscriber.ts", "node_modules/rxjs/src/internal/scheduler/animationFrameProvider.ts", "node_modules/rxjs/src/internal/util/ObjectUnsubscribedError.ts", "node_modules/rxjs/src/internal/Subject.ts", "node_modules/rxjs/src/internal/BehaviorSubject.ts", "node_modules/rxjs/src/internal/scheduler/dateTimestampProvider.ts", "node_modules/rxjs/src/internal/ReplaySubject.ts", "node_modules/rxjs/src/internal/scheduler/Action.ts", "node_modules/rxjs/src/internal/scheduler/intervalProvider.ts", "node_modules/rxjs/src/internal/scheduler/AsyncAction.ts", "node_modules/rxjs/src/internal/Scheduler.ts", "node_modules/rxjs/src/internal/scheduler/AsyncScheduler.ts", "node_modules/rxjs/src/internal/scheduler/async.ts", "node_modules/rxjs/src/internal/scheduler/QueueAction.ts", "node_modules/rxjs/src/internal/scheduler/QueueScheduler.ts", "node_modules/rxjs/src/internal/scheduler/queue.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameAction.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameScheduler.ts", "node_modules/rxjs/src/internal/scheduler/animationFrame.ts", "node_modules/rxjs/src/internal/observable/empty.ts", "node_modules/rxjs/src/internal/util/isScheduler.ts", "node_modules/rxjs/src/internal/util/args.ts", "node_modules/rxjs/src/internal/util/isArrayLike.ts", "node_modules/rxjs/src/internal/util/isPromise.ts", "node_modules/rxjs/src/internal/util/isInteropObservable.ts", "node_modules/rxjs/src/internal/util/isAsyncIterable.ts", "node_modules/rxjs/src/internal/util/throwUnobservableError.ts", "node_modules/rxjs/src/internal/symbol/iterator.ts", "node_modules/rxjs/src/internal/util/isIterable.ts", "node_modules/rxjs/src/internal/util/isReadableStreamLike.ts", "node_modules/rxjs/src/internal/observable/innerFrom.ts", "node_modules/rxjs/src/internal/util/executeSchedule.ts", "node_modules/rxjs/src/internal/operators/observeOn.ts", "node_modules/rxjs/src/internal/operators/subscribeOn.ts", "node_modules/rxjs/src/internal/scheduled/scheduleObservable.ts", "node_modules/rxjs/src/internal/scheduled/schedulePromise.ts", "node_modules/rxjs/src/internal/scheduled/scheduleArray.ts", "node_modules/rxjs/src/internal/scheduled/scheduleIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleAsyncIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleReadableStreamLike.ts", "node_modules/rxjs/src/internal/scheduled/scheduled.ts", "node_modules/rxjs/src/internal/observable/from.ts", "node_modules/rxjs/src/internal/observable/of.ts", "node_modules/rxjs/src/internal/observable/throwError.ts", "node_modules/rxjs/src/internal/util/EmptyError.ts", "node_modules/rxjs/src/internal/util/isDate.ts", "node_modules/rxjs/src/internal/operators/map.ts", "node_modules/rxjs/src/internal/util/mapOneOrManyArgs.ts", "node_modules/rxjs/src/internal/util/argsArgArrayOrObject.ts", "node_modules/rxjs/src/internal/util/createObject.ts", "node_modules/rxjs/src/internal/observable/combineLatest.ts", "node_modules/rxjs/src/internal/operators/mergeInternals.ts", "node_modules/rxjs/src/internal/operators/mergeMap.ts", "node_modules/rxjs/src/internal/operators/mergeAll.ts", "node_modules/rxjs/src/internal/operators/concatAll.ts", "node_modules/rxjs/src/internal/observable/concat.ts", "node_modules/rxjs/src/internal/observable/defer.ts", "node_modules/rxjs/src/internal/observable/fromEvent.ts", "node_modules/rxjs/src/internal/observable/fromEventPattern.ts", "node_modules/rxjs/src/internal/observable/timer.ts", "node_modules/rxjs/src/internal/observable/merge.ts", "node_modules/rxjs/src/internal/observable/never.ts", "node_modules/rxjs/src/internal/util/argsOrArgArray.ts", "node_modules/rxjs/src/internal/operators/filter.ts", "node_modules/rxjs/src/internal/observable/zip.ts", "node_modules/rxjs/src/internal/operators/audit.ts", "node_modules/rxjs/src/internal/operators/auditTime.ts", "node_modules/rxjs/src/internal/operators/bufferCount.ts", "node_modules/rxjs/src/internal/operators/catchError.ts", "node_modules/rxjs/src/internal/operators/scanInternals.ts", "node_modules/rxjs/src/internal/operators/combineLatest.ts", "node_modules/rxjs/src/internal/operators/combineLatestWith.ts", "node_modules/rxjs/src/internal/operators/debounce.ts", "node_modules/rxjs/src/internal/operators/debounceTime.ts", "node_modules/rxjs/src/internal/operators/defaultIfEmpty.ts", "node_modules/rxjs/src/internal/operators/take.ts", "node_modules/rxjs/src/internal/operators/ignoreElements.ts", "node_modules/rxjs/src/internal/operators/mapTo.ts", "node_modules/rxjs/src/internal/operators/delayWhen.ts", "node_modules/rxjs/src/internal/operators/delay.ts", "node_modules/rxjs/src/internal/operators/distinct.ts", "node_modules/rxjs/src/internal/operators/distinctUntilChanged.ts", "node_modules/rxjs/src/internal/operators/distinctUntilKeyChanged.ts", "node_modules/rxjs/src/internal/operators/throwIfEmpty.ts", "node_modules/rxjs/src/internal/operators/endWith.ts", "node_modules/rxjs/src/internal/operators/exhaustMap.ts", "node_modules/rxjs/src/internal/operators/finalize.ts", "node_modules/rxjs/src/internal/operators/first.ts", "node_modules/rxjs/src/internal/operators/takeLast.ts", "node_modules/rxjs/src/internal/operators/merge.ts", "node_modules/rxjs/src/internal/operators/mergeWith.ts", "node_modules/rxjs/src/internal/operators/repeat.ts", "node_modules/rxjs/src/internal/operators/scan.ts", "node_modules/rxjs/src/internal/operators/share.ts", "node_modules/rxjs/src/internal/operators/shareReplay.ts", "node_modules/rxjs/src/internal/operators/skip.ts", "node_modules/rxjs/src/internal/operators/skipUntil.ts", "node_modules/rxjs/src/internal/operators/startWith.ts", "node_modules/rxjs/src/internal/operators/switchMap.ts", "node_modules/rxjs/src/internal/operators/takeUntil.ts", "node_modules/rxjs/src/internal/operators/takeWhile.ts", "node_modules/rxjs/src/internal/operators/tap.ts", "node_modules/rxjs/src/internal/operators/throttle.ts", "node_modules/rxjs/src/internal/operators/throttleTime.ts", "node_modules/rxjs/src/internal/operators/withLatestFrom.ts", "node_modules/rxjs/src/internal/operators/zip.ts", "node_modules/rxjs/src/internal/operators/zipWith.ts", "src/templates/assets/javascripts/browser/document/index.ts", "src/templates/assets/javascripts/browser/element/_/index.ts", "src/templates/assets/javascripts/browser/element/focus/index.ts", "src/templates/assets/javascripts/browser/element/hover/index.ts", "src/templates/assets/javascripts/utilities/h/index.ts", "src/templates/assets/javascripts/utilities/round/index.ts", "src/templates/assets/javascripts/browser/script/index.ts", "src/templates/assets/javascripts/browser/element/size/_/index.ts", "src/templates/assets/javascripts/browser/element/size/content/index.ts", "src/templates/assets/javascripts/browser/element/offset/_/index.ts", "src/templates/assets/javascripts/browser/element/offset/content/index.ts", "src/templates/assets/javascripts/browser/element/visibility/index.ts", "src/templates/assets/javascripts/browser/toggle/index.ts", "src/templates/assets/javascripts/browser/keyboard/index.ts", "src/templates/assets/javascripts/browser/location/_/index.ts", "src/templates/assets/javascripts/browser/location/hash/index.ts", "src/templates/assets/javascripts/browser/media/index.ts", "src/templates/assets/javascripts/browser/request/index.ts", "src/templates/assets/javascripts/browser/viewport/offset/index.ts", "src/templates/assets/javascripts/browser/viewport/size/index.ts", "src/templates/assets/javascripts/browser/viewport/_/index.ts", "src/templates/assets/javascripts/browser/viewport/at/index.ts", "src/templates/assets/javascripts/browser/worker/index.ts", "src/templates/assets/javascripts/_/index.ts", "src/templates/assets/javascripts/components/_/index.ts", "src/templates/assets/javascripts/components/announce/index.ts", "src/templates/assets/javascripts/components/consent/index.ts", "src/templates/assets/javascripts/templates/tooltip/index.tsx", "src/templates/assets/javascripts/templates/annotation/index.tsx", "src/templates/assets/javascripts/templates/clipboard/index.tsx", "src/templates/assets/javascripts/templates/search/index.tsx", "src/templates/assets/javascripts/templates/source/index.tsx", "src/templates/assets/javascripts/templates/tabbed/index.tsx", "src/templates/assets/javascripts/templates/table/index.tsx", "src/templates/assets/javascripts/templates/version/index.tsx", "src/templates/assets/javascripts/components/tooltip2/index.ts", "src/templates/assets/javascripts/components/content/annotation/_/index.ts", "src/templates/assets/javascripts/components/content/annotation/list/index.ts", "src/templates/assets/javascripts/components/content/annotation/block/index.ts", "src/templates/assets/javascripts/components/content/code/_/index.ts", "src/templates/assets/javascripts/components/content/details/index.ts", "src/templates/assets/javascripts/components/content/link/index.ts", "src/templates/assets/javascripts/components/content/mermaid/index.css", "src/templates/assets/javascripts/components/content/mermaid/index.ts", "src/templates/assets/javascripts/components/content/table/index.ts", "src/templates/assets/javascripts/components/content/tabs/index.ts", "src/templates/assets/javascripts/components/content/_/index.ts", "src/templates/assets/javascripts/components/dialog/index.ts", "src/templates/assets/javascripts/components/tooltip/index.ts", "src/templates/assets/javascripts/components/header/_/index.ts", "src/templates/assets/javascripts/components/header/title/index.ts", "src/templates/assets/javascripts/components/main/index.ts", "src/templates/assets/javascripts/components/palette/index.ts", "src/templates/assets/javascripts/components/progress/index.ts", "src/templates/assets/javascripts/integrations/sitemap/index.ts", "src/templates/assets/javascripts/integrations/alternate/index.ts", "src/templates/assets/javascripts/integrations/clipboard/index.ts", "src/templates/assets/javascripts/integrations/instant/index.ts", "src/templates/assets/javascripts/integrations/search/highlighter/index.ts", "src/templates/assets/javascripts/integrations/search/worker/message/index.ts", "src/templates/assets/javascripts/integrations/search/worker/_/index.ts", "src/templates/assets/javascripts/integrations/version/findurl/index.ts", "src/templates/assets/javascripts/integrations/version/index.ts", "src/templates/assets/javascripts/components/search/query/index.ts", "src/templates/assets/javascripts/components/search/result/index.ts", "src/templates/assets/javascripts/components/search/share/index.ts", "src/templates/assets/javascripts/components/search/suggest/index.ts", "src/templates/assets/javascripts/components/search/_/index.ts", "src/templates/assets/javascripts/components/search/highlight/index.ts", "src/templates/assets/javascripts/components/sidebar/index.ts", "src/templates/assets/javascripts/components/source/facts/github/index.ts", "src/templates/assets/javascripts/components/source/facts/gitlab/index.ts", "src/templates/assets/javascripts/components/source/facts/_/index.ts", "src/templates/assets/javascripts/components/source/_/index.ts", "src/templates/assets/javascripts/components/tabs/index.ts", "src/templates/assets/javascripts/components/toc/index.ts", "src/templates/assets/javascripts/components/top/index.ts", "src/templates/assets/javascripts/patches/ellipsis/index.ts", "src/templates/assets/javascripts/patches/indeterminate/index.ts", "src/templates/assets/javascripts/patches/scrollfix/index.ts", "src/templates/assets/javascripts/patches/scrolllock/index.ts", "src/templates/assets/javascripts/polyfills/index.ts"], + "sourcesContent": ["(function (global, factory) {\n typeof exports === 'object' && typeof module !== 'undefined' ? factory() :\n typeof define === 'function' && define.amd ? define(factory) :\n (factory());\n}(this, (function () { 'use strict';\n\n /**\n * Applies the :focus-visible polyfill at the given scope.\n * A scope in this case is either the top-level Document or a Shadow Root.\n *\n * @param {(Document|ShadowRoot)} scope\n * @see https://github.com/WICG/focus-visible\n */\n function applyFocusVisiblePolyfill(scope) {\n var hadKeyboardEvent = true;\n var hadFocusVisibleRecently = false;\n var hadFocusVisibleRecentlyTimeout = null;\n\n var inputTypesAllowlist = {\n text: true,\n search: true,\n url: true,\n tel: true,\n email: true,\n password: true,\n number: true,\n date: true,\n month: true,\n week: true,\n time: true,\n datetime: true,\n 'datetime-local': true\n };\n\n /**\n * Helper function for legacy browsers and iframes which sometimes focus\n * elements like document, body, and non-interactive SVG.\n * @param {Element} el\n */\n function isValidFocusTarget(el) {\n if (\n el &&\n el !== document &&\n el.nodeName !== 'HTML' &&\n el.nodeName !== 'BODY' &&\n 'classList' in el &&\n 'contains' in el.classList\n ) {\n return true;\n }\n return false;\n }\n\n /**\n * Computes whether the given element should automatically trigger the\n * `focus-visible` class being added, i.e. whether it should always match\n * `:focus-visible` when focused.\n * @param {Element} el\n * @return {boolean}\n */\n function focusTriggersKeyboardModality(el) {\n var type = el.type;\n var tagName = el.tagName;\n\n if (tagName === 'INPUT' && inputTypesAllowlist[type] && !el.readOnly) {\n return true;\n }\n\n if (tagName === 'TEXTAREA' && !el.readOnly) {\n return true;\n }\n\n if (el.isContentEditable) {\n return true;\n }\n\n return false;\n }\n\n /**\n * Add the `focus-visible` class to the given element if it was not added by\n * the author.\n * @param {Element} el\n */\n function addFocusVisibleClass(el) {\n if (el.classList.contains('focus-visible')) {\n return;\n }\n el.classList.add('focus-visible');\n el.setAttribute('data-focus-visible-added', '');\n }\n\n /**\n * Remove the `focus-visible` class from the given element if it was not\n * originally added by the author.\n * @param {Element} el\n */\n function removeFocusVisibleClass(el) {\n if (!el.hasAttribute('data-focus-visible-added')) {\n return;\n }\n el.classList.remove('focus-visible');\n el.removeAttribute('data-focus-visible-added');\n }\n\n /**\n * If the most recent user interaction was via the keyboard;\n * and the key press did not include a meta, alt/option, or control key;\n * then the modality is keyboard. Otherwise, the modality is not keyboard.\n * Apply `focus-visible` to any current active element and keep track\n * of our keyboard modality state with `hadKeyboardEvent`.\n * @param {KeyboardEvent} e\n */\n function onKeyDown(e) {\n if (e.metaKey || e.altKey || e.ctrlKey) {\n return;\n }\n\n if (isValidFocusTarget(scope.activeElement)) {\n addFocusVisibleClass(scope.activeElement);\n }\n\n hadKeyboardEvent = true;\n }\n\n /**\n * If at any point a user clicks with a pointing device, ensure that we change\n * the modality away from keyboard.\n * This avoids the situation where a user presses a key on an already focused\n * element, and then clicks on a different element, focusing it with a\n * pointing device, while we still think we're in keyboard modality.\n * @param {Event} e\n */\n function onPointerDown(e) {\n hadKeyboardEvent = false;\n }\n\n /**\n * On `focus`, add the `focus-visible` class to the target if:\n * - the target received focus as a result of keyboard navigation, or\n * - the event target is an element that will likely require interaction\n * via the keyboard (e.g. a text box)\n * @param {Event} e\n */\n function onFocus(e) {\n // Prevent IE from focusing the document or HTML element.\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (hadKeyboardEvent || focusTriggersKeyboardModality(e.target)) {\n addFocusVisibleClass(e.target);\n }\n }\n\n /**\n * On `blur`, remove the `focus-visible` class from the target.\n * @param {Event} e\n */\n function onBlur(e) {\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (\n e.target.classList.contains('focus-visible') ||\n e.target.hasAttribute('data-focus-visible-added')\n ) {\n // To detect a tab/window switch, we look for a blur event followed\n // rapidly by a visibility change.\n // If we don't see a visibility change within 100ms, it's probably a\n // regular focus change.\n hadFocusVisibleRecently = true;\n window.clearTimeout(hadFocusVisibleRecentlyTimeout);\n hadFocusVisibleRecentlyTimeout = window.setTimeout(function() {\n hadFocusVisibleRecently = false;\n }, 100);\n removeFocusVisibleClass(e.target);\n }\n }\n\n /**\n * If the user changes tabs, keep track of whether or not the previously\n * focused element had .focus-visible.\n * @param {Event} e\n */\n function onVisibilityChange(e) {\n if (document.visibilityState === 'hidden') {\n // If the tab becomes active again, the browser will handle calling focus\n // on the element (Safari actually calls it twice).\n // If this tab change caused a blur on an element with focus-visible,\n // re-apply the class when the user switches back to the tab.\n if (hadFocusVisibleRecently) {\n hadKeyboardEvent = true;\n }\n addInitialPointerMoveListeners();\n }\n }\n\n /**\n * Add a group of listeners to detect usage of any pointing devices.\n * These listeners will be added when the polyfill first loads, and anytime\n * the window is blurred, so that they are active when the window regains\n * focus.\n */\n function addInitialPointerMoveListeners() {\n document.addEventListener('mousemove', onInitialPointerMove);\n document.addEventListener('mousedown', onInitialPointerMove);\n document.addEventListener('mouseup', onInitialPointerMove);\n document.addEventListener('pointermove', onInitialPointerMove);\n document.addEventListener('pointerdown', onInitialPointerMove);\n document.addEventListener('pointerup', onInitialPointerMove);\n document.addEventListener('touchmove', onInitialPointerMove);\n document.addEventListener('touchstart', onInitialPointerMove);\n document.addEventListener('touchend', onInitialPointerMove);\n }\n\n function removeInitialPointerMoveListeners() {\n document.removeEventListener('mousemove', onInitialPointerMove);\n document.removeEventListener('mousedown', onInitialPointerMove);\n document.removeEventListener('mouseup', onInitialPointerMove);\n document.removeEventListener('pointermove', onInitialPointerMove);\n document.removeEventListener('pointerdown', onInitialPointerMove);\n document.removeEventListener('pointerup', onInitialPointerMove);\n document.removeEventListener('touchmove', onInitialPointerMove);\n document.removeEventListener('touchstart', onInitialPointerMove);\n document.removeEventListener('touchend', onInitialPointerMove);\n }\n\n /**\n * When the polfyill first loads, assume the user is in keyboard modality.\n * If any event is received from a pointing device (e.g. mouse, pointer,\n * touch), turn off keyboard modality.\n * This accounts for situations where focus enters the page from the URL bar.\n * @param {Event} e\n */\n function onInitialPointerMove(e) {\n // Work around a Safari quirk that fires a mousemove on whenever the\n // window blurs, even if you're tabbing out of the page. \u00AF\\_(\u30C4)_/\u00AF\n if (e.target.nodeName && e.target.nodeName.toLowerCase() === 'html') {\n return;\n }\n\n hadKeyboardEvent = false;\n removeInitialPointerMoveListeners();\n }\n\n // For some kinds of state, we are interested in changes at the global scope\n // only. For example, global pointer input, global key presses and global\n // visibility change should affect the state at every scope:\n document.addEventListener('keydown', onKeyDown, true);\n document.addEventListener('mousedown', onPointerDown, true);\n document.addEventListener('pointerdown', onPointerDown, true);\n document.addEventListener('touchstart', onPointerDown, true);\n document.addEventListener('visibilitychange', onVisibilityChange, true);\n\n addInitialPointerMoveListeners();\n\n // For focus and blur, we specifically care about state changes in the local\n // scope. This is because focus / blur events that originate from within a\n // shadow root are not re-dispatched from the host element if it was already\n // the active element in its own scope:\n scope.addEventListener('focus', onFocus, true);\n scope.addEventListener('blur', onBlur, true);\n\n // We detect that a node is a ShadowRoot by ensuring that it is a\n // DocumentFragment and also has a host property. This check covers native\n // implementation and polyfill implementation transparently. If we only cared\n // about the native implementation, we could just check if the scope was\n // an instance of a ShadowRoot.\n if (scope.nodeType === Node.DOCUMENT_FRAGMENT_NODE && scope.host) {\n // Since a ShadowRoot is a special kind of DocumentFragment, it does not\n // have a root element to add a class to. So, we add this attribute to the\n // host element instead:\n scope.host.setAttribute('data-js-focus-visible', '');\n } else if (scope.nodeType === Node.DOCUMENT_NODE) {\n document.documentElement.classList.add('js-focus-visible');\n document.documentElement.setAttribute('data-js-focus-visible', '');\n }\n }\n\n // It is important to wrap all references to global window and document in\n // these checks to support server-side rendering use cases\n // @see https://github.com/WICG/focus-visible/issues/199\n if (typeof window !== 'undefined' && typeof document !== 'undefined') {\n // Make the polyfill helper globally available. This can be used as a signal\n // to interested libraries that wish to coordinate with the polyfill for e.g.,\n // applying the polyfill to a shadow root:\n window.applyFocusVisiblePolyfill = applyFocusVisiblePolyfill;\n\n // Notify interested libraries of the polyfill's presence, in case the\n // polyfill was loaded lazily:\n var event;\n\n try {\n event = new CustomEvent('focus-visible-polyfill-ready');\n } catch (error) {\n // IE11 does not support using CustomEvent as a constructor directly:\n event = document.createEvent('CustomEvent');\n event.initCustomEvent('focus-visible-polyfill-ready', false, false, {});\n }\n\n window.dispatchEvent(event);\n }\n\n if (typeof document !== 'undefined') {\n // Apply the polyfill to the global document, so that no JavaScript\n // coordination is required to use the polyfill in the top-level document:\n applyFocusVisiblePolyfill(document);\n }\n\n})));\n", "/*!\n * escape-html\n * Copyright(c) 2012-2013 TJ Holowaychuk\n * Copyright(c) 2015 Andreas Lubbe\n * Copyright(c) 2015 Tiancheng \"Timothy\" Gu\n * MIT Licensed\n */\n\n'use strict';\n\n/**\n * Module variables.\n * @private\n */\n\nvar matchHtmlRegExp = /[\"'&<>]/;\n\n/**\n * Module exports.\n * @public\n */\n\nmodule.exports = escapeHtml;\n\n/**\n * Escape special characters in the given string of html.\n *\n * @param {string} string The string to escape for inserting into HTML\n * @return {string}\n * @public\n */\n\nfunction escapeHtml(string) {\n var str = '' + string;\n var match = matchHtmlRegExp.exec(str);\n\n if (!match) {\n return str;\n }\n\n var escape;\n var html = '';\n var index = 0;\n var lastIndex = 0;\n\n for (index = match.index; index < str.length; index++) {\n switch (str.charCodeAt(index)) {\n case 34: // \"\n escape = '"';\n break;\n case 38: // &\n escape = '&';\n break;\n case 39: // '\n escape = ''';\n break;\n case 60: // <\n escape = '<';\n break;\n case 62: // >\n escape = '>';\n break;\n default:\n continue;\n }\n\n if (lastIndex !== index) {\n html += str.substring(lastIndex, index);\n }\n\n lastIndex = index + 1;\n html += escape;\n }\n\n return lastIndex !== index\n ? html + str.substring(lastIndex, index)\n : html;\n}\n", "/*!\n * clipboard.js v2.0.11\n * https://clipboardjs.com/\n *\n * Licensed MIT \u00A9 Zeno Rocha\n */\n(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory();\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"ClipboardJS\"] = factory();\n\telse\n\t\troot[\"ClipboardJS\"] = factory();\n})(this, function() {\nreturn /******/ (function() { // webpackBootstrap\n/******/ \tvar __webpack_modules__ = ({\n\n/***/ 686:\n/***/ (function(__unused_webpack_module, __webpack_exports__, __webpack_require__) {\n\n\"use strict\";\n\n// EXPORTS\n__webpack_require__.d(__webpack_exports__, {\n \"default\": function() { return /* binding */ clipboard; }\n});\n\n// EXTERNAL MODULE: ./node_modules/tiny-emitter/index.js\nvar tiny_emitter = __webpack_require__(279);\nvar tiny_emitter_default = /*#__PURE__*/__webpack_require__.n(tiny_emitter);\n// EXTERNAL MODULE: ./node_modules/good-listener/src/listen.js\nvar listen = __webpack_require__(370);\nvar listen_default = /*#__PURE__*/__webpack_require__.n(listen);\n// EXTERNAL MODULE: ./node_modules/select/src/select.js\nvar src_select = __webpack_require__(817);\nvar select_default = /*#__PURE__*/__webpack_require__.n(src_select);\n;// CONCATENATED MODULE: ./src/common/command.js\n/**\n * Executes a given operation type.\n * @param {String} type\n * @return {Boolean}\n */\nfunction command(type) {\n try {\n return document.execCommand(type);\n } catch (err) {\n return false;\n }\n}\n;// CONCATENATED MODULE: ./src/actions/cut.js\n\n\n/**\n * Cut action wrapper.\n * @param {String|HTMLElement} target\n * @return {String}\n */\n\nvar ClipboardActionCut = function ClipboardActionCut(target) {\n var selectedText = select_default()(target);\n command('cut');\n return selectedText;\n};\n\n/* harmony default export */ var actions_cut = (ClipboardActionCut);\n;// CONCATENATED MODULE: ./src/common/create-fake-element.js\n/**\n * Creates a fake textarea element with a value.\n * @param {String} value\n * @return {HTMLElement}\n */\nfunction createFakeElement(value) {\n var isRTL = document.documentElement.getAttribute('dir') === 'rtl';\n var fakeElement = document.createElement('textarea'); // Prevent zooming on iOS\n\n fakeElement.style.fontSize = '12pt'; // Reset box model\n\n fakeElement.style.border = '0';\n fakeElement.style.padding = '0';\n fakeElement.style.margin = '0'; // Move element out of screen horizontally\n\n fakeElement.style.position = 'absolute';\n fakeElement.style[isRTL ? 'right' : 'left'] = '-9999px'; // Move element to the same position vertically\n\n var yPosition = window.pageYOffset || document.documentElement.scrollTop;\n fakeElement.style.top = \"\".concat(yPosition, \"px\");\n fakeElement.setAttribute('readonly', '');\n fakeElement.value = value;\n return fakeElement;\n}\n;// CONCATENATED MODULE: ./src/actions/copy.js\n\n\n\n/**\n * Create fake copy action wrapper using a fake element.\n * @param {String} target\n * @param {Object} options\n * @return {String}\n */\n\nvar fakeCopyAction = function fakeCopyAction(value, options) {\n var fakeElement = createFakeElement(value);\n options.container.appendChild(fakeElement);\n var selectedText = select_default()(fakeElement);\n command('copy');\n fakeElement.remove();\n return selectedText;\n};\n/**\n * Copy action wrapper.\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @return {String}\n */\n\n\nvar ClipboardActionCopy = function ClipboardActionCopy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n var selectedText = '';\n\n if (typeof target === 'string') {\n selectedText = fakeCopyAction(target, options);\n } else if (target instanceof HTMLInputElement && !['text', 'search', 'url', 'tel', 'password'].includes(target === null || target === void 0 ? void 0 : target.type)) {\n // If input type doesn't support `setSelectionRange`. Simulate it. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange\n selectedText = fakeCopyAction(target.value, options);\n } else {\n selectedText = select_default()(target);\n command('copy');\n }\n\n return selectedText;\n};\n\n/* harmony default export */ var actions_copy = (ClipboardActionCopy);\n;// CONCATENATED MODULE: ./src/actions/default.js\nfunction _typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { _typeof = function _typeof(obj) { return typeof obj; }; } else { _typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return _typeof(obj); }\n\n\n\n/**\n * Inner function which performs selection from either `text` or `target`\n * properties and then executes copy or cut operations.\n * @param {Object} options\n */\n\nvar ClipboardActionDefault = function ClipboardActionDefault() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n // Defines base properties passed from constructor.\n var _options$action = options.action,\n action = _options$action === void 0 ? 'copy' : _options$action,\n container = options.container,\n target = options.target,\n text = options.text; // Sets the `action` to be performed which can be either 'copy' or 'cut'.\n\n if (action !== 'copy' && action !== 'cut') {\n throw new Error('Invalid \"action\" value, use either \"copy\" or \"cut\"');\n } // Sets the `target` property using an element that will be have its content copied.\n\n\n if (target !== undefined) {\n if (target && _typeof(target) === 'object' && target.nodeType === 1) {\n if (action === 'copy' && target.hasAttribute('disabled')) {\n throw new Error('Invalid \"target\" attribute. Please use \"readonly\" instead of \"disabled\" attribute');\n }\n\n if (action === 'cut' && (target.hasAttribute('readonly') || target.hasAttribute('disabled'))) {\n throw new Error('Invalid \"target\" attribute. You can\\'t cut text from elements with \"readonly\" or \"disabled\" attributes');\n }\n } else {\n throw new Error('Invalid \"target\" value, use a valid Element');\n }\n } // Define selection strategy based on `text` property.\n\n\n if (text) {\n return actions_copy(text, {\n container: container\n });\n } // Defines which selection strategy based on `target` property.\n\n\n if (target) {\n return action === 'cut' ? actions_cut(target) : actions_copy(target, {\n container: container\n });\n }\n};\n\n/* harmony default export */ var actions_default = (ClipboardActionDefault);\n;// CONCATENATED MODULE: ./src/clipboard.js\nfunction clipboard_typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { clipboard_typeof = function _typeof(obj) { return typeof obj; }; } else { clipboard_typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return clipboard_typeof(obj); }\n\nfunction _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError(\"Cannot call a class as a function\"); } }\n\nfunction _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if (\"value\" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } }\n\nfunction _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); return Constructor; }\n\nfunction _inherits(subClass, superClass) { if (typeof superClass !== \"function\" && superClass !== null) { throw new TypeError(\"Super expression must either be null or a function\"); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, writable: true, configurable: true } }); if (superClass) _setPrototypeOf(subClass, superClass); }\n\nfunction _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf || function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }\n\nfunction _createSuper(Derived) { var hasNativeReflectConstruct = _isNativeReflectConstruct(); return function _createSuperInternal() { var Super = _getPrototypeOf(Derived), result; if (hasNativeReflectConstruct) { var NewTarget = _getPrototypeOf(this).constructor; result = Reflect.construct(Super, arguments, NewTarget); } else { result = Super.apply(this, arguments); } return _possibleConstructorReturn(this, result); }; }\n\nfunction _possibleConstructorReturn(self, call) { if (call && (clipboard_typeof(call) === \"object\" || typeof call === \"function\")) { return call; } return _assertThisInitialized(self); }\n\nfunction _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError(\"this hasn't been initialised - super() hasn't been called\"); } return self; }\n\nfunction _isNativeReflectConstruct() { if (typeof Reflect === \"undefined\" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === \"function\") return true; try { Date.prototype.toString.call(Reflect.construct(Date, [], function () {})); return true; } catch (e) { return false; } }\n\nfunction _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }\n\n\n\n\n\n\n/**\n * Helper function to retrieve attribute value.\n * @param {String} suffix\n * @param {Element} element\n */\n\nfunction getAttributeValue(suffix, element) {\n var attribute = \"data-clipboard-\".concat(suffix);\n\n if (!element.hasAttribute(attribute)) {\n return;\n }\n\n return element.getAttribute(attribute);\n}\n/**\n * Base class which takes one or more elements, adds event listeners to them,\n * and instantiates a new `ClipboardAction` on each click.\n */\n\n\nvar Clipboard = /*#__PURE__*/function (_Emitter) {\n _inherits(Clipboard, _Emitter);\n\n var _super = _createSuper(Clipboard);\n\n /**\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n * @param {Object} options\n */\n function Clipboard(trigger, options) {\n var _this;\n\n _classCallCheck(this, Clipboard);\n\n _this = _super.call(this);\n\n _this.resolveOptions(options);\n\n _this.listenClick(trigger);\n\n return _this;\n }\n /**\n * Defines if attributes would be resolved using internal setter functions\n * or custom functions that were passed in the constructor.\n * @param {Object} options\n */\n\n\n _createClass(Clipboard, [{\n key: \"resolveOptions\",\n value: function resolveOptions() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n this.action = typeof options.action === 'function' ? options.action : this.defaultAction;\n this.target = typeof options.target === 'function' ? options.target : this.defaultTarget;\n this.text = typeof options.text === 'function' ? options.text : this.defaultText;\n this.container = clipboard_typeof(options.container) === 'object' ? options.container : document.body;\n }\n /**\n * Adds a click event listener to the passed trigger.\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n */\n\n }, {\n key: \"listenClick\",\n value: function listenClick(trigger) {\n var _this2 = this;\n\n this.listener = listen_default()(trigger, 'click', function (e) {\n return _this2.onClick(e);\n });\n }\n /**\n * Defines a new `ClipboardAction` on each click event.\n * @param {Event} e\n */\n\n }, {\n key: \"onClick\",\n value: function onClick(e) {\n var trigger = e.delegateTarget || e.currentTarget;\n var action = this.action(trigger) || 'copy';\n var text = actions_default({\n action: action,\n container: this.container,\n target: this.target(trigger),\n text: this.text(trigger)\n }); // Fires an event based on the copy operation result.\n\n this.emit(text ? 'success' : 'error', {\n action: action,\n text: text,\n trigger: trigger,\n clearSelection: function clearSelection() {\n if (trigger) {\n trigger.focus();\n }\n\n window.getSelection().removeAllRanges();\n }\n });\n }\n /**\n * Default `action` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultAction\",\n value: function defaultAction(trigger) {\n return getAttributeValue('action', trigger);\n }\n /**\n * Default `target` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultTarget\",\n value: function defaultTarget(trigger) {\n var selector = getAttributeValue('target', trigger);\n\n if (selector) {\n return document.querySelector(selector);\n }\n }\n /**\n * Allow fire programmatically a copy action\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @returns Text copied.\n */\n\n }, {\n key: \"defaultText\",\n\n /**\n * Default `text` lookup function.\n * @param {Element} trigger\n */\n value: function defaultText(trigger) {\n return getAttributeValue('text', trigger);\n }\n /**\n * Destroy lifecycle.\n */\n\n }, {\n key: \"destroy\",\n value: function destroy() {\n this.listener.destroy();\n }\n }], [{\n key: \"copy\",\n value: function copy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n return actions_copy(target, options);\n }\n /**\n * Allow fire programmatically a cut action\n * @param {String|HTMLElement} target\n * @returns Text cutted.\n */\n\n }, {\n key: \"cut\",\n value: function cut(target) {\n return actions_cut(target);\n }\n /**\n * Returns the support of the given action, or all actions if no action is\n * given.\n * @param {String} [action]\n */\n\n }, {\n key: \"isSupported\",\n value: function isSupported() {\n var action = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : ['copy', 'cut'];\n var actions = typeof action === 'string' ? [action] : action;\n var support = !!document.queryCommandSupported;\n actions.forEach(function (action) {\n support = support && !!document.queryCommandSupported(action);\n });\n return support;\n }\n }]);\n\n return Clipboard;\n}((tiny_emitter_default()));\n\n/* harmony default export */ var clipboard = (Clipboard);\n\n/***/ }),\n\n/***/ 828:\n/***/ (function(module) {\n\nvar DOCUMENT_NODE_TYPE = 9;\n\n/**\n * A polyfill for Element.matches()\n */\nif (typeof Element !== 'undefined' && !Element.prototype.matches) {\n var proto = Element.prototype;\n\n proto.matches = proto.matchesSelector ||\n proto.mozMatchesSelector ||\n proto.msMatchesSelector ||\n proto.oMatchesSelector ||\n proto.webkitMatchesSelector;\n}\n\n/**\n * Finds the closest parent that matches a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @return {Function}\n */\nfunction closest (element, selector) {\n while (element && element.nodeType !== DOCUMENT_NODE_TYPE) {\n if (typeof element.matches === 'function' &&\n element.matches(selector)) {\n return element;\n }\n element = element.parentNode;\n }\n}\n\nmodule.exports = closest;\n\n\n/***/ }),\n\n/***/ 438:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar closest = __webpack_require__(828);\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction _delegate(element, selector, type, callback, useCapture) {\n var listenerFn = listener.apply(this, arguments);\n\n element.addEventListener(type, listenerFn, useCapture);\n\n return {\n destroy: function() {\n element.removeEventListener(type, listenerFn, useCapture);\n }\n }\n}\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element|String|Array} [elements]\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction delegate(elements, selector, type, callback, useCapture) {\n // Handle the regular Element usage\n if (typeof elements.addEventListener === 'function') {\n return _delegate.apply(null, arguments);\n }\n\n // Handle Element-less usage, it defaults to global delegation\n if (typeof type === 'function') {\n // Use `document` as the first parameter, then apply arguments\n // This is a short way to .unshift `arguments` without running into deoptimizations\n return _delegate.bind(null, document).apply(null, arguments);\n }\n\n // Handle Selector-based usage\n if (typeof elements === 'string') {\n elements = document.querySelectorAll(elements);\n }\n\n // Handle Array-like based usage\n return Array.prototype.map.call(elements, function (element) {\n return _delegate(element, selector, type, callback, useCapture);\n });\n}\n\n/**\n * Finds closest match and invokes callback.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Function}\n */\nfunction listener(element, selector, type, callback) {\n return function(e) {\n e.delegateTarget = closest(e.target, selector);\n\n if (e.delegateTarget) {\n callback.call(element, e);\n }\n }\n}\n\nmodule.exports = delegate;\n\n\n/***/ }),\n\n/***/ 879:\n/***/ (function(__unused_webpack_module, exports) {\n\n/**\n * Check if argument is a HTML element.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.node = function(value) {\n return value !== undefined\n && value instanceof HTMLElement\n && value.nodeType === 1;\n};\n\n/**\n * Check if argument is a list of HTML elements.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.nodeList = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return value !== undefined\n && (type === '[object NodeList]' || type === '[object HTMLCollection]')\n && ('length' in value)\n && (value.length === 0 || exports.node(value[0]));\n};\n\n/**\n * Check if argument is a string.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.string = function(value) {\n return typeof value === 'string'\n || value instanceof String;\n};\n\n/**\n * Check if argument is a function.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.fn = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return type === '[object Function]';\n};\n\n\n/***/ }),\n\n/***/ 370:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar is = __webpack_require__(879);\nvar delegate = __webpack_require__(438);\n\n/**\n * Validates all params and calls the right\n * listener function based on its target type.\n *\n * @param {String|HTMLElement|HTMLCollection|NodeList} target\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listen(target, type, callback) {\n if (!target && !type && !callback) {\n throw new Error('Missing required arguments');\n }\n\n if (!is.string(type)) {\n throw new TypeError('Second argument must be a String');\n }\n\n if (!is.fn(callback)) {\n throw new TypeError('Third argument must be a Function');\n }\n\n if (is.node(target)) {\n return listenNode(target, type, callback);\n }\n else if (is.nodeList(target)) {\n return listenNodeList(target, type, callback);\n }\n else if (is.string(target)) {\n return listenSelector(target, type, callback);\n }\n else {\n throw new TypeError('First argument must be a String, HTMLElement, HTMLCollection, or NodeList');\n }\n}\n\n/**\n * Adds an event listener to a HTML element\n * and returns a remove listener function.\n *\n * @param {HTMLElement} node\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNode(node, type, callback) {\n node.addEventListener(type, callback);\n\n return {\n destroy: function() {\n node.removeEventListener(type, callback);\n }\n }\n}\n\n/**\n * Add an event listener to a list of HTML elements\n * and returns a remove listener function.\n *\n * @param {NodeList|HTMLCollection} nodeList\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNodeList(nodeList, type, callback) {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.addEventListener(type, callback);\n });\n\n return {\n destroy: function() {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.removeEventListener(type, callback);\n });\n }\n }\n}\n\n/**\n * Add an event listener to a selector\n * and returns a remove listener function.\n *\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenSelector(selector, type, callback) {\n return delegate(document.body, selector, type, callback);\n}\n\nmodule.exports = listen;\n\n\n/***/ }),\n\n/***/ 817:\n/***/ (function(module) {\n\nfunction select(element) {\n var selectedText;\n\n if (element.nodeName === 'SELECT') {\n element.focus();\n\n selectedText = element.value;\n }\n else if (element.nodeName === 'INPUT' || element.nodeName === 'TEXTAREA') {\n var isReadOnly = element.hasAttribute('readonly');\n\n if (!isReadOnly) {\n element.setAttribute('readonly', '');\n }\n\n element.select();\n element.setSelectionRange(0, element.value.length);\n\n if (!isReadOnly) {\n element.removeAttribute('readonly');\n }\n\n selectedText = element.value;\n }\n else {\n if (element.hasAttribute('contenteditable')) {\n element.focus();\n }\n\n var selection = window.getSelection();\n var range = document.createRange();\n\n range.selectNodeContents(element);\n selection.removeAllRanges();\n selection.addRange(range);\n\n selectedText = selection.toString();\n }\n\n return selectedText;\n}\n\nmodule.exports = select;\n\n\n/***/ }),\n\n/***/ 279:\n/***/ (function(module) {\n\nfunction E () {\n // Keep this empty so it's easier to inherit from\n // (via https://github.com/lipsmack from https://github.com/scottcorgan/tiny-emitter/issues/3)\n}\n\nE.prototype = {\n on: function (name, callback, ctx) {\n var e = this.e || (this.e = {});\n\n (e[name] || (e[name] = [])).push({\n fn: callback,\n ctx: ctx\n });\n\n return this;\n },\n\n once: function (name, callback, ctx) {\n var self = this;\n function listener () {\n self.off(name, listener);\n callback.apply(ctx, arguments);\n };\n\n listener._ = callback\n return this.on(name, listener, ctx);\n },\n\n emit: function (name) {\n var data = [].slice.call(arguments, 1);\n var evtArr = ((this.e || (this.e = {}))[name] || []).slice();\n var i = 0;\n var len = evtArr.length;\n\n for (i; i < len; i++) {\n evtArr[i].fn.apply(evtArr[i].ctx, data);\n }\n\n return this;\n },\n\n off: function (name, callback) {\n var e = this.e || (this.e = {});\n var evts = e[name];\n var liveEvents = [];\n\n if (evts && callback) {\n for (var i = 0, len = evts.length; i < len; i++) {\n if (evts[i].fn !== callback && evts[i].fn._ !== callback)\n liveEvents.push(evts[i]);\n }\n }\n\n // Remove event from queue to prevent memory leak\n // Suggested by https://github.com/lazd\n // Ref: https://github.com/scottcorgan/tiny-emitter/commit/c6ebfaa9bc973b33d110a84a307742b7cf94c953#commitcomment-5024910\n\n (liveEvents.length)\n ? e[name] = liveEvents\n : delete e[name];\n\n return this;\n }\n};\n\nmodule.exports = E;\nmodule.exports.TinyEmitter = E;\n\n\n/***/ })\n\n/******/ \t});\n/************************************************************************/\n/******/ \t// The module cache\n/******/ \tvar __webpack_module_cache__ = {};\n/******/ \t\n/******/ \t// The require function\n/******/ \tfunction __webpack_require__(moduleId) {\n/******/ \t\t// Check if module is in cache\n/******/ \t\tif(__webpack_module_cache__[moduleId]) {\n/******/ \t\t\treturn __webpack_module_cache__[moduleId].exports;\n/******/ \t\t}\n/******/ \t\t// Create a new module (and put it into the cache)\n/******/ \t\tvar module = __webpack_module_cache__[moduleId] = {\n/******/ \t\t\t// no module.id needed\n/******/ \t\t\t// no module.loaded needed\n/******/ \t\t\texports: {}\n/******/ \t\t};\n/******/ \t\n/******/ \t\t// Execute the module function\n/******/ \t\t__webpack_modules__[moduleId](module, module.exports, __webpack_require__);\n/******/ \t\n/******/ \t\t// Return the exports of the module\n/******/ \t\treturn module.exports;\n/******/ \t}\n/******/ \t\n/************************************************************************/\n/******/ \t/* webpack/runtime/compat get default export */\n/******/ \t!function() {\n/******/ \t\t// getDefaultExport function for compatibility with non-harmony modules\n/******/ \t\t__webpack_require__.n = function(module) {\n/******/ \t\t\tvar getter = module && module.__esModule ?\n/******/ \t\t\t\tfunction() { return module['default']; } :\n/******/ \t\t\t\tfunction() { return module; };\n/******/ \t\t\t__webpack_require__.d(getter, { a: getter });\n/******/ \t\t\treturn getter;\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/define property getters */\n/******/ \t!function() {\n/******/ \t\t// define getter functions for harmony exports\n/******/ \t\t__webpack_require__.d = function(exports, definition) {\n/******/ \t\t\tfor(var key in definition) {\n/******/ \t\t\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n/******/ \t\t\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n/******/ \t\t\t\t}\n/******/ \t\t\t}\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/hasOwnProperty shorthand */\n/******/ \t!function() {\n/******/ \t\t__webpack_require__.o = function(obj, prop) { return Object.prototype.hasOwnProperty.call(obj, prop); }\n/******/ \t}();\n/******/ \t\n/************************************************************************/\n/******/ \t// module exports must be returned from runtime so entry inlining is disabled\n/******/ \t// startup\n/******/ \t// Load entry module and return exports\n/******/ \treturn __webpack_require__(686);\n/******/ })()\n.default;\n});", "/*\n * Copyright (c) 2016-2025 Martin Donath \n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to\n * deal in the Software without restriction, including without limitation the\n * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\n * sell copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in\n * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\n * IN THE SOFTWARE.\n */\n\nimport \"focus-visible\"\n\nimport {\n EMPTY,\n NEVER,\n Observable,\n Subject,\n defer,\n delay,\n filter,\n map,\n merge,\n mergeWith,\n shareReplay,\n switchMap\n} from \"rxjs\"\n\nimport { configuration, feature } from \"./_\"\nimport {\n at,\n getActiveElement,\n getOptionalElement,\n requestJSON,\n setLocation,\n setToggle,\n watchDocument,\n watchKeyboard,\n watchLocation,\n watchLocationTarget,\n watchMedia,\n watchPrint,\n watchScript,\n watchViewport\n} from \"./browser\"\nimport {\n getComponentElement,\n getComponentElements,\n mountAnnounce,\n mountBackToTop,\n mountConsent,\n mountContent,\n mountDialog,\n mountHeader,\n mountHeaderTitle,\n mountPalette,\n mountProgress,\n mountSearch,\n mountSearchHiglight,\n mountSidebar,\n mountSource,\n mountTableOfContents,\n mountTabs,\n watchHeader,\n watchMain\n} from \"./components\"\nimport {\n SearchIndex,\n fetchSitemap,\n setupAlternate,\n setupClipboardJS,\n setupInstantNavigation,\n setupVersionSelector\n} from \"./integrations\"\nimport {\n patchEllipsis,\n patchIndeterminate,\n patchScrollfix,\n patchScrolllock\n} from \"./patches\"\nimport \"./polyfills\"\n\n/* ----------------------------------------------------------------------------\n * Functions - @todo refactor\n * ------------------------------------------------------------------------- */\n\n/**\n * Fetch search index\n *\n * @returns Search index observable\n */\nfunction fetchSearchIndex(): Observable {\n if (location.protocol === \"file:\") {\n return watchScript(\n `${new URL(\"search/search_index.js\", config.base)}`\n )\n .pipe(\n // @ts-ignore - @todo fix typings\n map(() => __index),\n shareReplay(1)\n )\n } else {\n return requestJSON(\n new URL(\"search/search_index.json\", config.base)\n )\n }\n}\n\n/* ----------------------------------------------------------------------------\n * Application\n * ------------------------------------------------------------------------- */\n\n/* Yay, JavaScript is available */\ndocument.documentElement.classList.remove(\"no-js\")\ndocument.documentElement.classList.add(\"js\")\n\n/* Set up navigation observables and subjects */\nconst document$ = watchDocument()\nconst location$ = watchLocation()\nconst target$ = watchLocationTarget(location$)\nconst keyboard$ = watchKeyboard()\n\n/* Set up media observables */\nconst viewport$ = watchViewport()\nconst tablet$ = watchMedia(\"(min-width: 60em)\")\nconst screen$ = watchMedia(\"(min-width: 76.25em)\")\nconst print$ = watchPrint()\n\n/* Retrieve search index, if search is enabled */\nconst config = configuration()\nconst index$ = document.forms.namedItem(\"search\")\n ? fetchSearchIndex()\n : NEVER\n\n/* Set up Clipboard.js integration */\nconst alert$ = new Subject()\nsetupClipboardJS({ alert$ })\n\n/* Set up language selector */\nsetupAlternate({ document$ })\n\n/* Set up progress indicator */\nconst progress$ = new Subject()\n\n/* Set up sitemap for instant navigation and previews */\nconst sitemap$ = fetchSitemap(config.base)\n\n/* Set up instant navigation, if enabled */\nif (feature(\"navigation.instant\"))\n setupInstantNavigation({ sitemap$, location$, viewport$, progress$ })\n .subscribe(document$)\n\n/* Set up version selector */\nif (config.version?.provider === \"mike\")\n setupVersionSelector({ document$ })\n\n/* Always close drawer and search on navigation */\nmerge(location$, target$)\n .pipe(\n delay(125)\n )\n .subscribe(() => {\n setToggle(\"drawer\", false)\n setToggle(\"search\", false)\n })\n\n/* Set up global keyboard handlers */\nkeyboard$\n .pipe(\n filter(({ mode }) => mode === \"global\")\n )\n .subscribe(key => {\n switch (key.type) {\n\n /* Go to previous page */\n case \"p\":\n case \",\":\n const prev = getOptionalElement(\"link[rel=prev]\")\n if (typeof prev !== \"undefined\")\n setLocation(prev)\n break\n\n /* Go to next page */\n case \"n\":\n case \".\":\n const next = getOptionalElement(\"link[rel=next]\")\n if (typeof next !== \"undefined\")\n setLocation(next)\n break\n\n /* Expand navigation, see https://bit.ly/3ZjG5io */\n case \"Enter\":\n const active = getActiveElement()\n if (active instanceof HTMLLabelElement)\n active.click()\n }\n })\n\n/* Set up patches */\npatchEllipsis({ viewport$, document$ })\npatchIndeterminate({ document$, tablet$ })\npatchScrollfix({ document$ })\npatchScrolllock({ viewport$, tablet$ })\n\n/* Set up header and main area observable */\nconst header$ = watchHeader(getComponentElement(\"header\"), { viewport$ })\nconst main$ = document$\n .pipe(\n map(() => getComponentElement(\"main\")),\n switchMap(el => watchMain(el, { viewport$, header$ })),\n shareReplay(1)\n )\n\n/* Set up control component observables */\nconst control$ = merge(\n\n /* Consent */\n ...getComponentElements(\"consent\")\n .map(el => mountConsent(el, { target$ })),\n\n /* Dialog */\n ...getComponentElements(\"dialog\")\n .map(el => mountDialog(el, { alert$ })),\n\n /* Color palette */\n ...getComponentElements(\"palette\")\n .map(el => mountPalette(el)),\n\n /* Progress bar */\n ...getComponentElements(\"progress\")\n .map(el => mountProgress(el, { progress$ })),\n\n /* Search */\n ...getComponentElements(\"search\")\n .map(el => mountSearch(el, { index$, keyboard$ })),\n\n /* Repository information */\n ...getComponentElements(\"source\")\n .map(el => mountSource(el))\n)\n\n/* Set up content component observables */\nconst content$ = defer(() => merge(\n\n /* Announcement bar */\n ...getComponentElements(\"announce\")\n .map(el => mountAnnounce(el)),\n\n /* Content */\n ...getComponentElements(\"content\")\n .map(el => mountContent(el, { sitemap$, viewport$, target$, print$ })),\n\n /* Search highlighting */\n ...getComponentElements(\"content\")\n .map(el => feature(\"search.highlight\")\n ? mountSearchHiglight(el, { index$, location$ })\n : EMPTY\n ),\n\n /* Header */\n ...getComponentElements(\"header\")\n .map(el => mountHeader(el, { viewport$, header$, main$ })),\n\n /* Header title */\n ...getComponentElements(\"header-title\")\n .map(el => mountHeaderTitle(el, { viewport$, header$ })),\n\n /* Sidebar */\n ...getComponentElements(\"sidebar\")\n .map(el => el.getAttribute(\"data-md-type\") === \"navigation\"\n ? at(screen$, () => mountSidebar(el, { viewport$, header$, main$ }))\n : at(tablet$, () => mountSidebar(el, { viewport$, header$, main$ }))\n ),\n\n /* Navigation tabs */\n ...getComponentElements(\"tabs\")\n .map(el => mountTabs(el, { viewport$, header$ })),\n\n /* Table of contents */\n ...getComponentElements(\"toc\")\n .map(el => mountTableOfContents(el, {\n viewport$, header$, main$, target$\n })),\n\n /* Back-to-top button */\n ...getComponentElements(\"top\")\n .map(el => mountBackToTop(el, { viewport$, header$, main$, target$ }))\n))\n\n/* Set up component observables */\nconst component$ = document$\n .pipe(\n switchMap(() => content$),\n mergeWith(control$),\n shareReplay(1)\n )\n\n/* Subscribe to all components */\ncomponent$.subscribe()\n\n/* ----------------------------------------------------------------------------\n * Exports\n * ------------------------------------------------------------------------- */\n\nwindow.document$ = document$ /* Document observable */\nwindow.location$ = location$ /* Location subject */\nwindow.target$ = target$ /* Location target observable */\nwindow.keyboard$ = keyboard$ /* Keyboard observable */\nwindow.viewport$ = viewport$ /* Viewport observable */\nwindow.tablet$ = tablet$ /* Media tablet observable */\nwindow.screen$ = screen$ /* Media screen observable */\nwindow.print$ = print$ /* Media print observable */\nwindow.alert$ = alert$ /* Alert subject */\nwindow.progress$ = progress$ /* Progress indicator subject */\nwindow.component$ = component$ /* Component observable */\n", "/******************************************************************************\nCopyright (c) Microsoft Corporation.\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY\nAND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM\nLOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR\nOTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR\nPERFORMANCE OF THIS SOFTWARE.\n***************************************************************************** */\n/* global Reflect, Promise, SuppressedError, Symbol, Iterator */\n\nvar extendStatics = function(d, b) {\n extendStatics = Object.setPrototypeOf ||\n ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||\n function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };\n return extendStatics(d, b);\n};\n\nexport function __extends(d, b) {\n if (typeof b !== \"function\" && b !== null)\n throw new TypeError(\"Class extends value \" + String(b) + \" is not a constructor or null\");\n extendStatics(d, b);\n function __() { this.constructor = d; }\n d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());\n}\n\nexport var __assign = function() {\n __assign = Object.assign || function __assign(t) {\n for (var s, i = 1, n = arguments.length; i < n; i++) {\n s = arguments[i];\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];\n }\n return t;\n }\n return __assign.apply(this, arguments);\n}\n\nexport function __rest(s, e) {\n var t = {};\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)\n t[p] = s[p];\n if (s != null && typeof Object.getOwnPropertySymbols === \"function\")\n for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {\n if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))\n t[p[i]] = s[p[i]];\n }\n return t;\n}\n\nexport function __decorate(decorators, target, key, desc) {\n var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;\n if (typeof Reflect === \"object\" && typeof Reflect.decorate === \"function\") r = Reflect.decorate(decorators, target, key, desc);\n else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;\n return c > 3 && r && Object.defineProperty(target, key, r), r;\n}\n\nexport function __param(paramIndex, decorator) {\n return function (target, key) { decorator(target, key, paramIndex); }\n}\n\nexport function __esDecorate(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {\n function accept(f) { if (f !== void 0 && typeof f !== \"function\") throw new TypeError(\"Function expected\"); return f; }\n var kind = contextIn.kind, key = kind === \"getter\" ? \"get\" : kind === \"setter\" ? \"set\" : \"value\";\n var target = !descriptorIn && ctor ? contextIn[\"static\"] ? ctor : ctor.prototype : null;\n var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});\n var _, done = false;\n for (var i = decorators.length - 1; i >= 0; i--) {\n var context = {};\n for (var p in contextIn) context[p] = p === \"access\" ? {} : contextIn[p];\n for (var p in contextIn.access) context.access[p] = contextIn.access[p];\n context.addInitializer = function (f) { if (done) throw new TypeError(\"Cannot add initializers after decoration has completed\"); extraInitializers.push(accept(f || null)); };\n var result = (0, decorators[i])(kind === \"accessor\" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);\n if (kind === \"accessor\") {\n if (result === void 0) continue;\n if (result === null || typeof result !== \"object\") throw new TypeError(\"Object expected\");\n if (_ = accept(result.get)) descriptor.get = _;\n if (_ = accept(result.set)) descriptor.set = _;\n if (_ = accept(result.init)) initializers.unshift(_);\n }\n else if (_ = accept(result)) {\n if (kind === \"field\") initializers.unshift(_);\n else descriptor[key] = _;\n }\n }\n if (target) Object.defineProperty(target, contextIn.name, descriptor);\n done = true;\n};\n\nexport function __runInitializers(thisArg, initializers, value) {\n var useValue = arguments.length > 2;\n for (var i = 0; i < initializers.length; i++) {\n value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);\n }\n return useValue ? value : void 0;\n};\n\nexport function __propKey(x) {\n return typeof x === \"symbol\" ? x : \"\".concat(x);\n};\n\nexport function __setFunctionName(f, name, prefix) {\n if (typeof name === \"symbol\") name = name.description ? \"[\".concat(name.description, \"]\") : \"\";\n return Object.defineProperty(f, \"name\", { configurable: true, value: prefix ? \"\".concat(prefix, \" \", name) : name });\n};\n\nexport function __metadata(metadataKey, metadataValue) {\n if (typeof Reflect === \"object\" && typeof Reflect.metadata === \"function\") return Reflect.metadata(metadataKey, metadataValue);\n}\n\nexport function __awaiter(thisArg, _arguments, P, generator) {\n function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }\n return new (P || (P = Promise))(function (resolve, reject) {\n function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }\n function rejected(value) { try { step(generator[\"throw\"](value)); } catch (e) { reject(e); } }\n function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }\n step((generator = generator.apply(thisArg, _arguments || [])).next());\n });\n}\n\nexport function __generator(thisArg, body) {\n var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === \"function\" ? Iterator : Object).prototype);\n return g.next = verb(0), g[\"throw\"] = verb(1), g[\"return\"] = verb(2), typeof Symbol === \"function\" && (g[Symbol.iterator] = function() { return this; }), g;\n function verb(n) { return function (v) { return step([n, v]); }; }\n function step(op) {\n if (f) throw new TypeError(\"Generator is already executing.\");\n while (g && (g = 0, op[0] && (_ = 0)), _) try {\n if (f = 1, y && (t = op[0] & 2 ? y[\"return\"] : op[0] ? y[\"throw\"] || ((t = y[\"return\"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;\n if (y = 0, t) op = [op[0] & 2, t.value];\n switch (op[0]) {\n case 0: case 1: t = op; break;\n case 4: _.label++; return { value: op[1], done: false };\n case 5: _.label++; y = op[1]; op = [0]; continue;\n case 7: op = _.ops.pop(); _.trys.pop(); continue;\n default:\n if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }\n if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }\n if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }\n if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }\n if (t[2]) _.ops.pop();\n _.trys.pop(); continue;\n }\n op = body.call(thisArg, _);\n } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }\n if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };\n }\n}\n\nexport var __createBinding = Object.create ? (function(o, m, k, k2) {\n if (k2 === undefined) k2 = k;\n var desc = Object.getOwnPropertyDescriptor(m, k);\n if (!desc || (\"get\" in desc ? !m.__esModule : desc.writable || desc.configurable)) {\n desc = { enumerable: true, get: function() { return m[k]; } };\n }\n Object.defineProperty(o, k2, desc);\n}) : (function(o, m, k, k2) {\n if (k2 === undefined) k2 = k;\n o[k2] = m[k];\n});\n\nexport function __exportStar(m, o) {\n for (var p in m) if (p !== \"default\" && !Object.prototype.hasOwnProperty.call(o, p)) __createBinding(o, m, p);\n}\n\nexport function __values(o) {\n var s = typeof Symbol === \"function\" && Symbol.iterator, m = s && o[s], i = 0;\n if (m) return m.call(o);\n if (o && typeof o.length === \"number\") return {\n next: function () {\n if (o && i >= o.length) o = void 0;\n return { value: o && o[i++], done: !o };\n }\n };\n throw new TypeError(s ? \"Object is not iterable.\" : \"Symbol.iterator is not defined.\");\n}\n\nexport function __read(o, n) {\n var m = typeof Symbol === \"function\" && o[Symbol.iterator];\n if (!m) return o;\n var i = m.call(o), r, ar = [], e;\n try {\n while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);\n }\n catch (error) { e = { error: error }; }\n finally {\n try {\n if (r && !r.done && (m = i[\"return\"])) m.call(i);\n }\n finally { if (e) throw e.error; }\n }\n return ar;\n}\n\n/** @deprecated */\nexport function __spread() {\n for (var ar = [], i = 0; i < arguments.length; i++)\n ar = ar.concat(__read(arguments[i]));\n return ar;\n}\n\n/** @deprecated */\nexport function __spreadArrays() {\n for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;\n for (var r = Array(s), k = 0, i = 0; i < il; i++)\n for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)\n r[k] = a[j];\n return r;\n}\n\nexport function __spreadArray(to, from, pack) {\n if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {\n if (ar || !(i in from)) {\n if (!ar) ar = Array.prototype.slice.call(from, 0, i);\n ar[i] = from[i];\n }\n }\n return to.concat(ar || Array.prototype.slice.call(from));\n}\n\nexport function __await(v) {\n return this instanceof __await ? (this.v = v, this) : new __await(v);\n}\n\nexport function __asyncGenerator(thisArg, _arguments, generator) {\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\n var g = generator.apply(thisArg, _arguments || []), i, q = [];\n return i = Object.create((typeof AsyncIterator === \"function\" ? AsyncIterator : Object).prototype), verb(\"next\"), verb(\"throw\"), verb(\"return\", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;\n function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }\n function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }\n function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }\n function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }\n function fulfill(value) { resume(\"next\", value); }\n function reject(value) { resume(\"throw\", value); }\n function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }\n}\n\nexport function __asyncDelegator(o) {\n var i, p;\n return i = {}, verb(\"next\"), verb(\"throw\", function (e) { throw e; }), verb(\"return\"), i[Symbol.iterator] = function () { return this; }, i;\n function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }\n}\n\nexport function __asyncValues(o) {\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\n var m = o[Symbol.asyncIterator], i;\n return m ? m.call(o) : (o = typeof __values === \"function\" ? __values(o) : o[Symbol.iterator](), i = {}, verb(\"next\"), verb(\"throw\"), verb(\"return\"), i[Symbol.asyncIterator] = function () { return this; }, i);\n function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }\n function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }\n}\n\nexport function __makeTemplateObject(cooked, raw) {\n if (Object.defineProperty) { Object.defineProperty(cooked, \"raw\", { value: raw }); } else { cooked.raw = raw; }\n return cooked;\n};\n\nvar __setModuleDefault = Object.create ? (function(o, v) {\n Object.defineProperty(o, \"default\", { enumerable: true, value: v });\n}) : function(o, v) {\n o[\"default\"] = v;\n};\n\nexport function __importStar(mod) {\n if (mod && mod.__esModule) return mod;\n var result = {};\n if (mod != null) for (var k in mod) if (k !== \"default\" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);\n __setModuleDefault(result, mod);\n return result;\n}\n\nexport function __importDefault(mod) {\n return (mod && mod.__esModule) ? mod : { default: mod };\n}\n\nexport function __classPrivateFieldGet(receiver, state, kind, f) {\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a getter\");\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot read private member from an object whose class did not declare it\");\n return kind === \"m\" ? f : kind === \"a\" ? f.call(receiver) : f ? f.value : state.get(receiver);\n}\n\nexport function __classPrivateFieldSet(receiver, state, value, kind, f) {\n if (kind === \"m\") throw new TypeError(\"Private method is not writable\");\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a setter\");\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot write private member to an object whose class did not declare it\");\n return (kind === \"a\" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;\n}\n\nexport function __classPrivateFieldIn(state, receiver) {\n if (receiver === null || (typeof receiver !== \"object\" && typeof receiver !== \"function\")) throw new TypeError(\"Cannot use 'in' operator on non-object\");\n return typeof state === \"function\" ? receiver === state : state.has(receiver);\n}\n\nexport function __addDisposableResource(env, value, async) {\n if (value !== null && value !== void 0) {\n if (typeof value !== \"object\" && typeof value !== \"function\") throw new TypeError(\"Object expected.\");\n var dispose, inner;\n if (async) {\n if (!Symbol.asyncDispose) throw new TypeError(\"Symbol.asyncDispose is not defined.\");\n dispose = value[Symbol.asyncDispose];\n }\n if (dispose === void 0) {\n if (!Symbol.dispose) throw new TypeError(\"Symbol.dispose is not defined.\");\n dispose = value[Symbol.dispose];\n if (async) inner = dispose;\n }\n if (typeof dispose !== \"function\") throw new TypeError(\"Object not disposable.\");\n if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };\n env.stack.push({ value: value, dispose: dispose, async: async });\n }\n else if (async) {\n env.stack.push({ async: true });\n }\n return value;\n}\n\nvar _SuppressedError = typeof SuppressedError === \"function\" ? SuppressedError : function (error, suppressed, message) {\n var e = new Error(message);\n return e.name = \"SuppressedError\", e.error = error, e.suppressed = suppressed, e;\n};\n\nexport function __disposeResources(env) {\n function fail(e) {\n env.error = env.hasError ? new _SuppressedError(e, env.error, \"An error was suppressed during disposal.\") : e;\n env.hasError = true;\n }\n var r, s = 0;\n function next() {\n while (r = env.stack.pop()) {\n try {\n if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);\n if (r.dispose) {\n var result = r.dispose.call(r.value);\n if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });\n }\n else s |= 1;\n }\n catch (e) {\n fail(e);\n }\n }\n if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();\n if (env.hasError) throw env.error;\n }\n return next();\n}\n\nexport default {\n __extends,\n __assign,\n __rest,\n __decorate,\n __param,\n __metadata,\n __awaiter,\n __generator,\n __createBinding,\n __exportStar,\n __values,\n __read,\n __spread,\n __spreadArrays,\n __spreadArray,\n __await,\n __asyncGenerator,\n __asyncDelegator,\n __asyncValues,\n __makeTemplateObject,\n __importStar,\n __importDefault,\n __classPrivateFieldGet,\n __classPrivateFieldSet,\n __classPrivateFieldIn,\n __addDisposableResource,\n __disposeResources,\n};\n", "/**\n * Returns true if the object is a function.\n * @param value The value to check\n */\nexport function isFunction(value: any): value is (...args: any[]) => any {\n return typeof value === 'function';\n}\n", "/**\n * Used to create Error subclasses until the community moves away from ES5.\n *\n * This is because compiling from TypeScript down to ES5 has issues with subclassing Errors\n * as well as other built-in types: https://github.com/Microsoft/TypeScript/issues/12123\n *\n * @param createImpl A factory function to create the actual constructor implementation. The returned\n * function should be a named function that calls `_super` internally.\n */\nexport function createErrorClass(createImpl: (_super: any) => any): T {\n const _super = (instance: any) => {\n Error.call(instance);\n instance.stack = new Error().stack;\n };\n\n const ctorFunc = createImpl(_super);\n ctorFunc.prototype = Object.create(Error.prototype);\n ctorFunc.prototype.constructor = ctorFunc;\n return ctorFunc;\n}\n", "import { createErrorClass } from './createErrorClass';\n\nexport interface UnsubscriptionError extends Error {\n readonly errors: any[];\n}\n\nexport interface UnsubscriptionErrorCtor {\n /**\n * @deprecated Internal implementation detail. Do not construct error instances.\n * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269\n */\n new (errors: any[]): UnsubscriptionError;\n}\n\n/**\n * An error thrown when one or more errors have occurred during the\n * `unsubscribe` of a {@link Subscription}.\n */\nexport const UnsubscriptionError: UnsubscriptionErrorCtor = createErrorClass(\n (_super) =>\n function UnsubscriptionErrorImpl(this: any, errors: (Error | string)[]) {\n _super(this);\n this.message = errors\n ? `${errors.length} errors occurred during unsubscription:\n${errors.map((err, i) => `${i + 1}) ${err.toString()}`).join('\\n ')}`\n : '';\n this.name = 'UnsubscriptionError';\n this.errors = errors;\n }\n);\n", "/**\n * Removes an item from an array, mutating it.\n * @param arr The array to remove the item from\n * @param item The item to remove\n */\nexport function arrRemove(arr: T[] | undefined | null, item: T) {\n if (arr) {\n const index = arr.indexOf(item);\n 0 <= index && arr.splice(index, 1);\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { UnsubscriptionError } from './util/UnsubscriptionError';\nimport { SubscriptionLike, TeardownLogic, Unsubscribable } from './types';\nimport { arrRemove } from './util/arrRemove';\n\n/**\n * Represents a disposable resource, such as the execution of an Observable. A\n * Subscription has one important method, `unsubscribe`, that takes no argument\n * and just disposes the resource held by the subscription.\n *\n * Additionally, subscriptions may be grouped together through the `add()`\n * method, which will attach a child Subscription to the current Subscription.\n * When a Subscription is unsubscribed, all its children (and its grandchildren)\n * will be unsubscribed as well.\n */\nexport class Subscription implements SubscriptionLike {\n public static EMPTY = (() => {\n const empty = new Subscription();\n empty.closed = true;\n return empty;\n })();\n\n /**\n * A flag to indicate whether this Subscription has already been unsubscribed.\n */\n public closed = false;\n\n private _parentage: Subscription[] | Subscription | null = null;\n\n /**\n * The list of registered finalizers to execute upon unsubscription. Adding and removing from this\n * list occurs in the {@link #add} and {@link #remove} methods.\n */\n private _finalizers: Exclude[] | null = null;\n\n /**\n * @param initialTeardown A function executed first as part of the finalization\n * process that is kicked off when {@link #unsubscribe} is called.\n */\n constructor(private initialTeardown?: () => void) {}\n\n /**\n * Disposes the resources held by the subscription. May, for instance, cancel\n * an ongoing Observable execution or cancel any other type of work that\n * started when the Subscription was created.\n */\n unsubscribe(): void {\n let errors: any[] | undefined;\n\n if (!this.closed) {\n this.closed = true;\n\n // Remove this from it's parents.\n const { _parentage } = this;\n if (_parentage) {\n this._parentage = null;\n if (Array.isArray(_parentage)) {\n for (const parent of _parentage) {\n parent.remove(this);\n }\n } else {\n _parentage.remove(this);\n }\n }\n\n const { initialTeardown: initialFinalizer } = this;\n if (isFunction(initialFinalizer)) {\n try {\n initialFinalizer();\n } catch (e) {\n errors = e instanceof UnsubscriptionError ? e.errors : [e];\n }\n }\n\n const { _finalizers } = this;\n if (_finalizers) {\n this._finalizers = null;\n for (const finalizer of _finalizers) {\n try {\n execFinalizer(finalizer);\n } catch (err) {\n errors = errors ?? [];\n if (err instanceof UnsubscriptionError) {\n errors = [...errors, ...err.errors];\n } else {\n errors.push(err);\n }\n }\n }\n }\n\n if (errors) {\n throw new UnsubscriptionError(errors);\n }\n }\n }\n\n /**\n * Adds a finalizer to this subscription, so that finalization will be unsubscribed/called\n * when this subscription is unsubscribed. If this subscription is already {@link #closed},\n * because it has already been unsubscribed, then whatever finalizer is passed to it\n * will automatically be executed (unless the finalizer itself is also a closed subscription).\n *\n * Closed Subscriptions cannot be added as finalizers to any subscription. Adding a closed\n * subscription to a any subscription will result in no operation. (A noop).\n *\n * Adding a subscription to itself, or adding `null` or `undefined` will not perform any\n * operation at all. (A noop).\n *\n * `Subscription` instances that are added to this instance will automatically remove themselves\n * if they are unsubscribed. Functions and {@link Unsubscribable} objects that you wish to remove\n * will need to be removed manually with {@link #remove}\n *\n * @param teardown The finalization logic to add to this subscription.\n */\n add(teardown: TeardownLogic): void {\n // Only add the finalizer if it's not undefined\n // and don't add a subscription to itself.\n if (teardown && teardown !== this) {\n if (this.closed) {\n // If this subscription is already closed,\n // execute whatever finalizer is handed to it automatically.\n execFinalizer(teardown);\n } else {\n if (teardown instanceof Subscription) {\n // We don't add closed subscriptions, and we don't add the same subscription\n // twice. Subscription unsubscribe is idempotent.\n if (teardown.closed || teardown._hasParent(this)) {\n return;\n }\n teardown._addParent(this);\n }\n (this._finalizers = this._finalizers ?? []).push(teardown);\n }\n }\n }\n\n /**\n * Checks to see if a this subscription already has a particular parent.\n * This will signal that this subscription has already been added to the parent in question.\n * @param parent the parent to check for\n */\n private _hasParent(parent: Subscription) {\n const { _parentage } = this;\n return _parentage === parent || (Array.isArray(_parentage) && _parentage.includes(parent));\n }\n\n /**\n * Adds a parent to this subscription so it can be removed from the parent if it\n * unsubscribes on it's own.\n *\n * NOTE: THIS ASSUMES THAT {@link _hasParent} HAS ALREADY BEEN CHECKED.\n * @param parent The parent subscription to add\n */\n private _addParent(parent: Subscription) {\n const { _parentage } = this;\n this._parentage = Array.isArray(_parentage) ? (_parentage.push(parent), _parentage) : _parentage ? [_parentage, parent] : parent;\n }\n\n /**\n * Called on a child when it is removed via {@link #remove}.\n * @param parent The parent to remove\n */\n private _removeParent(parent: Subscription) {\n const { _parentage } = this;\n if (_parentage === parent) {\n this._parentage = null;\n } else if (Array.isArray(_parentage)) {\n arrRemove(_parentage, parent);\n }\n }\n\n /**\n * Removes a finalizer from this subscription that was previously added with the {@link #add} method.\n *\n * Note that `Subscription` instances, when unsubscribed, will automatically remove themselves\n * from every other `Subscription` they have been added to. This means that using the `remove` method\n * is not a common thing and should be used thoughtfully.\n *\n * If you add the same finalizer instance of a function or an unsubscribable object to a `Subscription` instance\n * more than once, you will need to call `remove` the same number of times to remove all instances.\n *\n * All finalizer instances are removed to free up memory upon unsubscription.\n *\n * @param teardown The finalizer to remove from this subscription\n */\n remove(teardown: Exclude): void {\n const { _finalizers } = this;\n _finalizers && arrRemove(_finalizers, teardown);\n\n if (teardown instanceof Subscription) {\n teardown._removeParent(this);\n }\n }\n}\n\nexport const EMPTY_SUBSCRIPTION = Subscription.EMPTY;\n\nexport function isSubscription(value: any): value is Subscription {\n return (\n value instanceof Subscription ||\n (value && 'closed' in value && isFunction(value.remove) && isFunction(value.add) && isFunction(value.unsubscribe))\n );\n}\n\nfunction execFinalizer(finalizer: Unsubscribable | (() => void)) {\n if (isFunction(finalizer)) {\n finalizer();\n } else {\n finalizer.unsubscribe();\n }\n}\n", "import { Subscriber } from './Subscriber';\nimport { ObservableNotification } from './types';\n\n/**\n * The {@link GlobalConfig} object for RxJS. It is used to configure things\n * like how to react on unhandled errors.\n */\nexport const config: GlobalConfig = {\n onUnhandledError: null,\n onStoppedNotification: null,\n Promise: undefined,\n useDeprecatedSynchronousErrorHandling: false,\n useDeprecatedNextContext: false,\n};\n\n/**\n * The global configuration object for RxJS, used to configure things\n * like how to react on unhandled errors. Accessible via {@link config}\n * object.\n */\nexport interface GlobalConfig {\n /**\n * A registration point for unhandled errors from RxJS. These are errors that\n * cannot were not handled by consuming code in the usual subscription path. For\n * example, if you have this configured, and you subscribe to an observable without\n * providing an error handler, errors from that subscription will end up here. This\n * will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onUnhandledError: ((err: any) => void) | null;\n\n /**\n * A registration point for notifications that cannot be sent to subscribers because they\n * have completed, errored or have been explicitly unsubscribed. By default, next, complete\n * and error notifications sent to stopped subscribers are noops. However, sometimes callers\n * might want a different behavior. For example, with sources that attempt to report errors\n * to stopped subscribers, a caller can configure RxJS to throw an unhandled error instead.\n * This will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onStoppedNotification: ((notification: ObservableNotification, subscriber: Subscriber) => void) | null;\n\n /**\n * The promise constructor used by default for {@link Observable#toPromise toPromise} and {@link Observable#forEach forEach}\n * methods.\n *\n * @deprecated As of version 8, RxJS will no longer support this sort of injection of a\n * Promise constructor. If you need a Promise implementation other than native promises,\n * please polyfill/patch Promise as you see appropriate. Will be removed in v8.\n */\n Promise?: PromiseConstructorLike;\n\n /**\n * If true, turns on synchronous error rethrowing, which is a deprecated behavior\n * in v6 and higher. This behavior enables bad patterns like wrapping a subscribe\n * call in a try/catch block. It also enables producer interference, a nasty bug\n * where a multicast can be broken for all observers by a downstream consumer with\n * an unhandled error. DO NOT USE THIS FLAG UNLESS IT'S NEEDED TO BUY TIME\n * FOR MIGRATION REASONS.\n *\n * @deprecated As of version 8, RxJS will no longer support synchronous throwing\n * of unhandled errors. All errors will be thrown on a separate call stack to prevent bad\n * behaviors described above. Will be removed in v8.\n */\n useDeprecatedSynchronousErrorHandling: boolean;\n\n /**\n * If true, enables an as-of-yet undocumented feature from v5: The ability to access\n * `unsubscribe()` via `this` context in `next` functions created in observers passed\n * to `subscribe`.\n *\n * This is being removed because the performance was severely problematic, and it could also cause\n * issues when types other than POJOs are passed to subscribe as subscribers, as they will likely have\n * their `this` context overwritten.\n *\n * @deprecated As of version 8, RxJS will no longer support altering the\n * context of next functions provided as part of an observer to Subscribe. Instead,\n * you will have access to a subscription or a signal or token that will allow you to do things like\n * unsubscribe and test closed status. Will be removed in v8.\n */\n useDeprecatedNextContext: boolean;\n}\n", "import type { TimerHandle } from './timerHandle';\ntype SetTimeoutFunction = (handler: () => void, timeout?: number, ...args: any[]) => TimerHandle;\ntype ClearTimeoutFunction = (handle: TimerHandle) => void;\n\ninterface TimeoutProvider {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n delegate:\n | {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n }\n | undefined;\n}\n\nexport const timeoutProvider: TimeoutProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n setTimeout(handler: () => void, timeout?: number, ...args) {\n const { delegate } = timeoutProvider;\n if (delegate?.setTimeout) {\n return delegate.setTimeout(handler, timeout, ...args);\n }\n return setTimeout(handler, timeout, ...args);\n },\n clearTimeout(handle) {\n const { delegate } = timeoutProvider;\n return (delegate?.clearTimeout || clearTimeout)(handle as any);\n },\n delegate: undefined,\n};\n", "import { config } from '../config';\nimport { timeoutProvider } from '../scheduler/timeoutProvider';\n\n/**\n * Handles an error on another job either with the user-configured {@link onUnhandledError},\n * or by throwing it on that new job so it can be picked up by `window.onerror`, `process.on('error')`, etc.\n *\n * This should be called whenever there is an error that is out-of-band with the subscription\n * or when an error hits a terminal boundary of the subscription and no error handler was provided.\n *\n * @param err the error to report\n */\nexport function reportUnhandledError(err: any) {\n timeoutProvider.setTimeout(() => {\n const { onUnhandledError } = config;\n if (onUnhandledError) {\n // Execute the user-configured error handler.\n onUnhandledError(err);\n } else {\n // Throw so it is picked up by the runtime's uncaught error mechanism.\n throw err;\n }\n });\n}\n", "/* tslint:disable:no-empty */\nexport function noop() { }\n", "import { CompleteNotification, NextNotification, ErrorNotification } from './types';\n\n/**\n * A completion object optimized for memory use and created to be the\n * same \"shape\" as other notifications in v8.\n * @internal\n */\nexport const COMPLETE_NOTIFICATION = (() => createNotification('C', undefined, undefined) as CompleteNotification)();\n\n/**\n * Internal use only. Creates an optimized error notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function errorNotification(error: any): ErrorNotification {\n return createNotification('E', undefined, error) as any;\n}\n\n/**\n * Internal use only. Creates an optimized next notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function nextNotification(value: T) {\n return createNotification('N', value, undefined) as NextNotification;\n}\n\n/**\n * Ensures that all notifications created internally have the same \"shape\" in v8.\n *\n * TODO: This is only exported to support a crazy legacy test in `groupBy`.\n * @internal\n */\nexport function createNotification(kind: 'N' | 'E' | 'C', value: any, error: any) {\n return {\n kind,\n value,\n error,\n };\n}\n", "import { config } from '../config';\n\nlet context: { errorThrown: boolean; error: any } | null = null;\n\n/**\n * Handles dealing with errors for super-gross mode. Creates a context, in which\n * any synchronously thrown errors will be passed to {@link captureError}. Which\n * will record the error such that it will be rethrown after the call back is complete.\n * TODO: Remove in v8\n * @param cb An immediately executed function.\n */\nexport function errorContext(cb: () => void) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n const isRoot = !context;\n if (isRoot) {\n context = { errorThrown: false, error: null };\n }\n cb();\n if (isRoot) {\n const { errorThrown, error } = context!;\n context = null;\n if (errorThrown) {\n throw error;\n }\n }\n } else {\n // This is the general non-deprecated path for everyone that\n // isn't crazy enough to use super-gross mode (useDeprecatedSynchronousErrorHandling)\n cb();\n }\n}\n\n/**\n * Captures errors only in super-gross mode.\n * @param err the error to capture\n */\nexport function captureError(err: any) {\n if (config.useDeprecatedSynchronousErrorHandling && context) {\n context.errorThrown = true;\n context.error = err;\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { Observer, ObservableNotification } from './types';\nimport { isSubscription, Subscription } from './Subscription';\nimport { config } from './config';\nimport { reportUnhandledError } from './util/reportUnhandledError';\nimport { noop } from './util/noop';\nimport { nextNotification, errorNotification, COMPLETE_NOTIFICATION } from './NotificationFactories';\nimport { timeoutProvider } from './scheduler/timeoutProvider';\nimport { captureError } from './util/errorContext';\n\n/**\n * Implements the {@link Observer} interface and extends the\n * {@link Subscription} class. While the {@link Observer} is the public API for\n * consuming the values of an {@link Observable}, all Observers get converted to\n * a Subscriber, in order to provide Subscription-like capabilities such as\n * `unsubscribe`. Subscriber is a common type in RxJS, and crucial for\n * implementing operators, but it is rarely used as a public API.\n */\nexport class Subscriber extends Subscription implements Observer {\n /**\n * A static factory for a Subscriber, given a (potentially partial) definition\n * of an Observer.\n * @param next The `next` callback of an Observer.\n * @param error The `error` callback of an\n * Observer.\n * @param complete The `complete` callback of an\n * Observer.\n * @return A Subscriber wrapping the (partially defined)\n * Observer represented by the given arguments.\n * @deprecated Do not use. Will be removed in v8. There is no replacement for this\n * method, and there is no reason to be creating instances of `Subscriber` directly.\n * If you have a specific use case, please file an issue.\n */\n static create(next?: (x?: T) => void, error?: (e?: any) => void, complete?: () => void): Subscriber {\n return new SafeSubscriber(next, error, complete);\n }\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected isStopped: boolean = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected destination: Subscriber | Observer; // this `any` is the escape hatch to erase extra type param (e.g. R)\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * There is no reason to directly create an instance of Subscriber. This type is exported for typings reasons.\n */\n constructor(destination?: Subscriber | Observer) {\n super();\n if (destination) {\n this.destination = destination;\n // Automatically chain subscriptions together here.\n // if destination is a Subscription, then it is a Subscriber.\n if (isSubscription(destination)) {\n destination.add(this);\n }\n } else {\n this.destination = EMPTY_OBSERVER;\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `next` from\n * the Observable, with a value. The Observable may call this method 0 or more\n * times.\n * @param value The `next` value.\n */\n next(value: T): void {\n if (this.isStopped) {\n handleStoppedNotification(nextNotification(value), this);\n } else {\n this._next(value!);\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `error` from\n * the Observable, with an attached `Error`. Notifies the Observer that\n * the Observable has experienced an error condition.\n * @param err The `error` exception.\n */\n error(err?: any): void {\n if (this.isStopped) {\n handleStoppedNotification(errorNotification(err), this);\n } else {\n this.isStopped = true;\n this._error(err);\n }\n }\n\n /**\n * The {@link Observer} callback to receive a valueless notification of type\n * `complete` from the Observable. Notifies the Observer that the Observable\n * has finished sending push-based notifications.\n */\n complete(): void {\n if (this.isStopped) {\n handleStoppedNotification(COMPLETE_NOTIFICATION, this);\n } else {\n this.isStopped = true;\n this._complete();\n }\n }\n\n unsubscribe(): void {\n if (!this.closed) {\n this.isStopped = true;\n super.unsubscribe();\n this.destination = null!;\n }\n }\n\n protected _next(value: T): void {\n this.destination.next(value);\n }\n\n protected _error(err: any): void {\n try {\n this.destination.error(err);\n } finally {\n this.unsubscribe();\n }\n }\n\n protected _complete(): void {\n try {\n this.destination.complete();\n } finally {\n this.unsubscribe();\n }\n }\n}\n\n/**\n * This bind is captured here because we want to be able to have\n * compatibility with monoid libraries that tend to use a method named\n * `bind`. In particular, a library called Monio requires this.\n */\nconst _bind = Function.prototype.bind;\n\nfunction bind any>(fn: Fn, thisArg: any): Fn {\n return _bind.call(fn, thisArg);\n}\n\n/**\n * Internal optimization only, DO NOT EXPOSE.\n * @internal\n */\nclass ConsumerObserver implements Observer {\n constructor(private partialObserver: Partial>) {}\n\n next(value: T): void {\n const { partialObserver } = this;\n if (partialObserver.next) {\n try {\n partialObserver.next(value);\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n\n error(err: any): void {\n const { partialObserver } = this;\n if (partialObserver.error) {\n try {\n partialObserver.error(err);\n } catch (error) {\n handleUnhandledError(error);\n }\n } else {\n handleUnhandledError(err);\n }\n }\n\n complete(): void {\n const { partialObserver } = this;\n if (partialObserver.complete) {\n try {\n partialObserver.complete();\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n}\n\nexport class SafeSubscriber extends Subscriber {\n constructor(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((e?: any) => void) | null,\n complete?: (() => void) | null\n ) {\n super();\n\n let partialObserver: Partial>;\n if (isFunction(observerOrNext) || !observerOrNext) {\n // The first argument is a function, not an observer. The next\n // two arguments *could* be observers, or they could be empty.\n partialObserver = {\n next: (observerOrNext ?? undefined) as ((value: T) => void) | undefined,\n error: error ?? undefined,\n complete: complete ?? undefined,\n };\n } else {\n // The first argument is a partial observer.\n let context: any;\n if (this && config.useDeprecatedNextContext) {\n // This is a deprecated path that made `this.unsubscribe()` available in\n // next handler functions passed to subscribe. This only exists behind a flag\n // now, as it is *very* slow.\n context = Object.create(observerOrNext);\n context.unsubscribe = () => this.unsubscribe();\n partialObserver = {\n next: observerOrNext.next && bind(observerOrNext.next, context),\n error: observerOrNext.error && bind(observerOrNext.error, context),\n complete: observerOrNext.complete && bind(observerOrNext.complete, context),\n };\n } else {\n // The \"normal\" path. Just use the partial observer directly.\n partialObserver = observerOrNext;\n }\n }\n\n // Wrap the partial observer to ensure it's a full observer, and\n // make sure proper error handling is accounted for.\n this.destination = new ConsumerObserver(partialObserver);\n }\n}\n\nfunction handleUnhandledError(error: any) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n captureError(error);\n } else {\n // Ideal path, we report this as an unhandled error,\n // which is thrown on a new call stack.\n reportUnhandledError(error);\n }\n}\n\n/**\n * An error handler used when no error handler was supplied\n * to the SafeSubscriber -- meaning no error handler was supplied\n * do the `subscribe` call on our observable.\n * @param err The error to handle\n */\nfunction defaultErrorHandler(err: any) {\n throw err;\n}\n\n/**\n * A handler for notifications that cannot be sent to a stopped subscriber.\n * @param notification The notification being sent.\n * @param subscriber The stopped subscriber.\n */\nfunction handleStoppedNotification(notification: ObservableNotification, subscriber: Subscriber) {\n const { onStoppedNotification } = config;\n onStoppedNotification && timeoutProvider.setTimeout(() => onStoppedNotification(notification, subscriber));\n}\n\n/**\n * The observer used as a stub for subscriptions where the user did not\n * pass any arguments to `subscribe`. Comes with the default error handling\n * behavior.\n */\nexport const EMPTY_OBSERVER: Readonly> & { closed: true } = {\n closed: true,\n next: noop,\n error: defaultErrorHandler,\n complete: noop,\n};\n", "/**\n * Symbol.observable or a string \"@@observable\". Used for interop\n *\n * @deprecated We will no longer be exporting this symbol in upcoming versions of RxJS.\n * Instead polyfill and use Symbol.observable directly *or* use https://www.npmjs.com/package/symbol-observable\n */\nexport const observable: string | symbol = (() => (typeof Symbol === 'function' && Symbol.observable) || '@@observable')();\n", "/**\n * This function takes one parameter and just returns it. Simply put,\n * this is like `(x: T): T => x`.\n *\n * ## Examples\n *\n * This is useful in some cases when using things like `mergeMap`\n *\n * ```ts\n * import { interval, take, map, range, mergeMap, identity } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(5));\n *\n * const result$ = source$.pipe(\n * map(i => range(i)),\n * mergeMap(identity) // same as mergeMap(x => x)\n * );\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * Or when you want to selectively apply an operator\n *\n * ```ts\n * import { interval, take, identity } from 'rxjs';\n *\n * const shouldLimit = () => Math.random() < 0.5;\n *\n * const source$ = interval(1000);\n *\n * const result$ = source$.pipe(shouldLimit() ? take(5) : identity);\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * @param x Any value that is returned by this function\n * @returns The value passed as the first parameter to this function\n */\nexport function identity(x: T): T {\n return x;\n}\n", "import { identity } from './identity';\nimport { UnaryFunction } from '../types';\n\nexport function pipe(): typeof identity;\nexport function pipe(fn1: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction, fn3: UnaryFunction): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction,\n ...fns: UnaryFunction[]\n): UnaryFunction;\n\n/**\n * pipe() can be called on one or more functions, each of which can take one argument (\"UnaryFunction\")\n * and uses it to return a value.\n * It returns a function that takes one argument, passes it to the first UnaryFunction, and then\n * passes the result to the next one, passes that result to the next one, and so on. \n */\nexport function pipe(...fns: Array>): UnaryFunction {\n return pipeFromArray(fns);\n}\n\n/** @internal */\nexport function pipeFromArray(fns: Array>): UnaryFunction {\n if (fns.length === 0) {\n return identity as UnaryFunction;\n }\n\n if (fns.length === 1) {\n return fns[0];\n }\n\n return function piped(input: T): R {\n return fns.reduce((prev: any, fn: UnaryFunction) => fn(prev), input as any);\n };\n}\n", "import { Operator } from './Operator';\nimport { SafeSubscriber, Subscriber } from './Subscriber';\nimport { isSubscription, Subscription } from './Subscription';\nimport { TeardownLogic, OperatorFunction, Subscribable, Observer } from './types';\nimport { observable as Symbol_observable } from './symbol/observable';\nimport { pipeFromArray } from './util/pipe';\nimport { config } from './config';\nimport { isFunction } from './util/isFunction';\nimport { errorContext } from './util/errorContext';\n\n/**\n * A representation of any set of values over any amount of time. This is the most basic building block\n * of RxJS.\n */\nexport class Observable implements Subscribable {\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n source: Observable | undefined;\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n operator: Operator | undefined;\n\n /**\n * @param subscribe The function that is called when the Observable is\n * initially subscribed to. This function is given a Subscriber, to which new values\n * can be `next`ed, or an `error` method can be called to raise an error, or\n * `complete` can be called to notify of a successful completion.\n */\n constructor(subscribe?: (this: Observable, subscriber: Subscriber) => TeardownLogic) {\n if (subscribe) {\n this._subscribe = subscribe;\n }\n }\n\n // HACK: Since TypeScript inherits static properties too, we have to\n // fight against TypeScript here so Subject can have a different static create signature\n /**\n * Creates a new Observable by calling the Observable constructor\n * @param subscribe the subscriber function to be passed to the Observable constructor\n * @return A new observable.\n * @deprecated Use `new Observable()` instead. Will be removed in v8.\n */\n static create: (...args: any[]) => any = (subscribe?: (subscriber: Subscriber) => TeardownLogic) => {\n return new Observable(subscribe);\n };\n\n /**\n * Creates a new Observable, with this Observable instance as the source, and the passed\n * operator defined as the new observable's operator.\n * @param operator the operator defining the operation to take on the observable\n * @return A new observable with the Operator applied.\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * If you have implemented an operator using `lift`, it is recommended that you create an\n * operator by simply returning `new Observable()` directly. See \"Creating new operators from\n * scratch\" section here: https://rxjs.dev/guide/operators\n */\n lift(operator?: Operator): Observable {\n const observable = new Observable();\n observable.source = this;\n observable.operator = operator;\n return observable;\n }\n\n subscribe(observerOrNext?: Partial> | ((value: T) => void)): Subscription;\n /** @deprecated Instead of passing separate callback arguments, use an observer argument. Signatures taking separate callback arguments will be removed in v8. Details: https://rxjs.dev/deprecations/subscribe-arguments */\n subscribe(next?: ((value: T) => void) | null, error?: ((error: any) => void) | null, complete?: (() => void) | null): Subscription;\n /**\n * Invokes an execution of an Observable and registers Observer handlers for notifications it will emit.\n *\n * Use it when you have all these Observables, but still nothing is happening.\n *\n * `subscribe` is not a regular operator, but a method that calls Observable's internal `subscribe` function. It\n * might be for example a function that you passed to Observable's constructor, but most of the time it is\n * a library implementation, which defines what will be emitted by an Observable, and when it be will emitted. This means\n * that calling `subscribe` is actually the moment when Observable starts its work, not when it is created, as it is often\n * the thought.\n *\n * Apart from starting the execution of an Observable, this method allows you to listen for values\n * that an Observable emits, as well as for when it completes or errors. You can achieve this in two\n * of the following ways.\n *\n * The first way is creating an object that implements {@link Observer} interface. It should have methods\n * defined by that interface, but note that it should be just a regular JavaScript object, which you can create\n * yourself in any way you want (ES6 class, classic function constructor, object literal etc.). In particular, do\n * not attempt to use any RxJS implementation details to create Observers - you don't need them. Remember also\n * that your object does not have to implement all methods. If you find yourself creating a method that doesn't\n * do anything, you can simply omit it. Note however, if the `error` method is not provided and an error happens,\n * it will be thrown asynchronously. Errors thrown asynchronously cannot be caught using `try`/`catch`. Instead,\n * use the {@link onUnhandledError} configuration option or use a runtime handler (like `window.onerror` or\n * `process.on('error)`) to be notified of unhandled errors. Because of this, it's recommended that you provide\n * an `error` method to avoid missing thrown errors.\n *\n * The second way is to give up on Observer object altogether and simply provide callback functions in place of its methods.\n * This means you can provide three functions as arguments to `subscribe`, where the first function is equivalent\n * of a `next` method, the second of an `error` method and the third of a `complete` method. Just as in case of an Observer,\n * if you do not need to listen for something, you can omit a function by passing `undefined` or `null`,\n * since `subscribe` recognizes these functions by where they were placed in function call. When it comes\n * to the `error` function, as with an Observer, if not provided, errors emitted by an Observable will be thrown asynchronously.\n *\n * You can, however, subscribe with no parameters at all. This may be the case where you're not interested in terminal events\n * and you also handled emissions internally by using operators (e.g. using `tap`).\n *\n * Whichever style of calling `subscribe` you use, in both cases it returns a Subscription object.\n * This object allows you to call `unsubscribe` on it, which in turn will stop the work that an Observable does and will clean\n * up all resources that an Observable used. Note that cancelling a subscription will not call `complete` callback\n * provided to `subscribe` function, which is reserved for a regular completion signal that comes from an Observable.\n *\n * Remember that callbacks provided to `subscribe` are not guaranteed to be called asynchronously.\n * It is an Observable itself that decides when these functions will be called. For example {@link of}\n * by default emits all its values synchronously. Always check documentation for how given Observable\n * will behave when subscribed and if its default behavior can be modified with a `scheduler`.\n *\n * #### Examples\n *\n * Subscribe with an {@link guide/observer Observer}\n *\n * ```ts\n * import { of } from 'rxjs';\n *\n * const sumObserver = {\n * sum: 0,\n * next(value) {\n * console.log('Adding: ' + value);\n * this.sum = this.sum + value;\n * },\n * error() {\n * // We actually could just remove this method,\n * // since we do not really care about errors right now.\n * },\n * complete() {\n * console.log('Sum equals: ' + this.sum);\n * }\n * };\n *\n * of(1, 2, 3) // Synchronously emits 1, 2, 3 and then completes.\n * .subscribe(sumObserver);\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Subscribe with functions ({@link deprecations/subscribe-arguments deprecated})\n *\n * ```ts\n * import { of } from 'rxjs'\n *\n * let sum = 0;\n *\n * of(1, 2, 3).subscribe(\n * value => {\n * console.log('Adding: ' + value);\n * sum = sum + value;\n * },\n * undefined,\n * () => console.log('Sum equals: ' + sum)\n * );\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Cancel a subscription\n *\n * ```ts\n * import { interval } from 'rxjs';\n *\n * const subscription = interval(1000).subscribe({\n * next(num) {\n * console.log(num)\n * },\n * complete() {\n * // Will not be called, even when cancelling subscription.\n * console.log('completed!');\n * }\n * });\n *\n * setTimeout(() => {\n * subscription.unsubscribe();\n * console.log('unsubscribed!');\n * }, 2500);\n *\n * // Logs:\n * // 0 after 1s\n * // 1 after 2s\n * // 'unsubscribed!' after 2.5s\n * ```\n *\n * @param observerOrNext Either an {@link Observer} with some or all callback methods,\n * or the `next` handler that is called for each value emitted from the subscribed Observable.\n * @param error A handler for a terminal event resulting from an error. If no error handler is provided,\n * the error will be thrown asynchronously as unhandled.\n * @param complete A handler for a terminal event resulting from successful completion.\n * @return A subscription reference to the registered handlers.\n */\n subscribe(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((error: any) => void) | null,\n complete?: (() => void) | null\n ): Subscription {\n const subscriber = isSubscriber(observerOrNext) ? observerOrNext : new SafeSubscriber(observerOrNext, error, complete);\n\n errorContext(() => {\n const { operator, source } = this;\n subscriber.add(\n operator\n ? // We're dealing with a subscription in the\n // operator chain to one of our lifted operators.\n operator.call(subscriber, source)\n : source\n ? // If `source` has a value, but `operator` does not, something that\n // had intimate knowledge of our API, like our `Subject`, must have\n // set it. We're going to just call `_subscribe` directly.\n this._subscribe(subscriber)\n : // In all other cases, we're likely wrapping a user-provided initializer\n // function, so we need to catch errors and handle them appropriately.\n this._trySubscribe(subscriber)\n );\n });\n\n return subscriber;\n }\n\n /** @internal */\n protected _trySubscribe(sink: Subscriber): TeardownLogic {\n try {\n return this._subscribe(sink);\n } catch (err) {\n // We don't need to return anything in this case,\n // because it's just going to try to `add()` to a subscription\n // above.\n sink.error(err);\n }\n }\n\n /**\n * Used as a NON-CANCELLABLE means of subscribing to an observable, for use with\n * APIs that expect promises, like `async/await`. You cannot unsubscribe from this.\n *\n * **WARNING**: Only use this with observables you *know* will complete. If the source\n * observable does not complete, you will end up with a promise that is hung up, and\n * potentially all of the state of an async function hanging out in memory. To avoid\n * this situation, look into adding something like {@link timeout}, {@link take},\n * {@link takeWhile}, or {@link takeUntil} amongst others.\n *\n * #### Example\n *\n * ```ts\n * import { interval, take } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(4));\n *\n * async function getTotal() {\n * let total = 0;\n *\n * await source$.forEach(value => {\n * total += value;\n * console.log('observable -> ' + value);\n * });\n *\n * return total;\n * }\n *\n * getTotal().then(\n * total => console.log('Total: ' + total)\n * );\n *\n * // Expected:\n * // 'observable -> 0'\n * // 'observable -> 1'\n * // 'observable -> 2'\n * // 'observable -> 3'\n * // 'Total: 6'\n * ```\n *\n * @param next A handler for each value emitted by the observable.\n * @return A promise that either resolves on observable completion or\n * rejects with the handled error.\n */\n forEach(next: (value: T) => void): Promise;\n\n /**\n * @param next a handler for each value emitted by the observable\n * @param promiseCtor a constructor function used to instantiate the Promise\n * @return a promise that either resolves on observable completion or\n * rejects with the handled error\n * @deprecated Passing a Promise constructor will no longer be available\n * in upcoming versions of RxJS. This is because it adds weight to the library, for very\n * little benefit. If you need this functionality, it is recommended that you either\n * polyfill Promise, or you create an adapter to convert the returned native promise\n * to whatever promise implementation you wanted. Will be removed in v8.\n */\n forEach(next: (value: T) => void, promiseCtor: PromiseConstructorLike): Promise;\n\n forEach(next: (value: T) => void, promiseCtor?: PromiseConstructorLike): Promise {\n promiseCtor = getPromiseCtor(promiseCtor);\n\n return new promiseCtor((resolve, reject) => {\n const subscriber = new SafeSubscriber({\n next: (value) => {\n try {\n next(value);\n } catch (err) {\n reject(err);\n subscriber.unsubscribe();\n }\n },\n error: reject,\n complete: resolve,\n });\n this.subscribe(subscriber);\n }) as Promise;\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): TeardownLogic {\n return this.source?.subscribe(subscriber);\n }\n\n /**\n * An interop point defined by the es7-observable spec https://github.com/zenparsing/es-observable\n * @return This instance of the observable.\n */\n [Symbol_observable]() {\n return this;\n }\n\n /* tslint:disable:max-line-length */\n pipe(): Observable;\n pipe(op1: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction, op3: OperatorFunction): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction,\n op9: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction,\n op9: OperatorFunction,\n ...operations: OperatorFunction[]\n ): Observable;\n /* tslint:enable:max-line-length */\n\n /**\n * Used to stitch together functional operators into a chain.\n *\n * ## Example\n *\n * ```ts\n * import { interval, filter, map, scan } from 'rxjs';\n *\n * interval(1000)\n * .pipe(\n * filter(x => x % 2 === 0),\n * map(x => x + x),\n * scan((acc, x) => acc + x)\n * )\n * .subscribe(x => console.log(x));\n * ```\n *\n * @return The Observable result of all the operators having been called\n * in the order they were passed in.\n */\n pipe(...operations: OperatorFunction[]): Observable {\n return pipeFromArray(operations)(this);\n }\n\n /* tslint:disable:max-line-length */\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(): Promise;\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(PromiseCtor: typeof Promise): Promise;\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(PromiseCtor: PromiseConstructorLike): Promise;\n /* tslint:enable:max-line-length */\n\n /**\n * Subscribe to this Observable and get a Promise resolving on\n * `complete` with the last emission (if any).\n *\n * **WARNING**: Only use this with observables you *know* will complete. If the source\n * observable does not complete, you will end up with a promise that is hung up, and\n * potentially all of the state of an async function hanging out in memory. To avoid\n * this situation, look into adding something like {@link timeout}, {@link take},\n * {@link takeWhile}, or {@link takeUntil} amongst others.\n *\n * @param [promiseCtor] a constructor function used to instantiate\n * the Promise\n * @return A Promise that resolves with the last value emit, or\n * rejects on an error. If there were no emissions, Promise\n * resolves with undefined.\n * @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise\n */\n toPromise(promiseCtor?: PromiseConstructorLike): Promise {\n promiseCtor = getPromiseCtor(promiseCtor);\n\n return new promiseCtor((resolve, reject) => {\n let value: T | undefined;\n this.subscribe(\n (x: T) => (value = x),\n (err: any) => reject(err),\n () => resolve(value)\n );\n }) as Promise;\n }\n}\n\n/**\n * Decides between a passed promise constructor from consuming code,\n * A default configured promise constructor, and the native promise\n * constructor and returns it. If nothing can be found, it will throw\n * an error.\n * @param promiseCtor The optional promise constructor to passed by consuming code\n */\nfunction getPromiseCtor(promiseCtor: PromiseConstructorLike | undefined) {\n return promiseCtor ?? config.Promise ?? Promise;\n}\n\nfunction isObserver(value: any): value is Observer {\n return value && isFunction(value.next) && isFunction(value.error) && isFunction(value.complete);\n}\n\nfunction isSubscriber(value: any): value is Subscriber {\n return (value && value instanceof Subscriber) || (isObserver(value) && isSubscription(value));\n}\n", "import { Observable } from '../Observable';\nimport { Subscriber } from '../Subscriber';\nimport { OperatorFunction } from '../types';\nimport { isFunction } from './isFunction';\n\n/**\n * Used to determine if an object is an Observable with a lift function.\n */\nexport function hasLift(source: any): source is { lift: InstanceType['lift'] } {\n return isFunction(source?.lift);\n}\n\n/**\n * Creates an `OperatorFunction`. Used to define operators throughout the library in a concise way.\n * @param init The logic to connect the liftedSource to the subscriber at the moment of subscription.\n */\nexport function operate(\n init: (liftedSource: Observable, subscriber: Subscriber) => (() => void) | void\n): OperatorFunction {\n return (source: Observable) => {\n if (hasLift(source)) {\n return source.lift(function (this: Subscriber, liftedSource: Observable) {\n try {\n return init(liftedSource, this);\n } catch (err) {\n this.error(err);\n }\n });\n }\n throw new TypeError('Unable to lift unknown Observable type');\n };\n}\n", "import { Subscriber } from '../Subscriber';\n\n/**\n * Creates an instance of an `OperatorSubscriber`.\n * @param destination The downstream subscriber.\n * @param onNext Handles next values, only called if this subscriber is not stopped or closed. Any\n * error that occurs in this function is caught and sent to the `error` method of this subscriber.\n * @param onError Handles errors from the subscription, any errors that occur in this handler are caught\n * and send to the `destination` error handler.\n * @param onComplete Handles completion notification from the subscription. Any errors that occur in\n * this handler are sent to the `destination` error handler.\n * @param onFinalize Additional teardown logic here. This will only be called on teardown if the\n * subscriber itself is not already closed. This is called after all other teardown logic is executed.\n */\nexport function createOperatorSubscriber(\n destination: Subscriber,\n onNext?: (value: T) => void,\n onComplete?: () => void,\n onError?: (err: any) => void,\n onFinalize?: () => void\n): Subscriber {\n return new OperatorSubscriber(destination, onNext, onComplete, onError, onFinalize);\n}\n\n/**\n * A generic helper for allowing operators to be created with a Subscriber and\n * use closures to capture necessary state from the operator function itself.\n */\nexport class OperatorSubscriber extends Subscriber {\n /**\n * Creates an instance of an `OperatorSubscriber`.\n * @param destination The downstream subscriber.\n * @param onNext Handles next values, only called if this subscriber is not stopped or closed. Any\n * error that occurs in this function is caught and sent to the `error` method of this subscriber.\n * @param onError Handles errors from the subscription, any errors that occur in this handler are caught\n * and send to the `destination` error handler.\n * @param onComplete Handles completion notification from the subscription. Any errors that occur in\n * this handler are sent to the `destination` error handler.\n * @param onFinalize Additional finalization logic here. This will only be called on finalization if the\n * subscriber itself is not already closed. This is called after all other finalization logic is executed.\n * @param shouldUnsubscribe An optional check to see if an unsubscribe call should truly unsubscribe.\n * NOTE: This currently **ONLY** exists to support the strange behavior of {@link groupBy}, where unsubscription\n * to the resulting observable does not actually disconnect from the source if there are active subscriptions\n * to any grouped observable. (DO NOT EXPOSE OR USE EXTERNALLY!!!)\n */\n constructor(\n destination: Subscriber,\n onNext?: (value: T) => void,\n onComplete?: () => void,\n onError?: (err: any) => void,\n private onFinalize?: () => void,\n private shouldUnsubscribe?: () => boolean\n ) {\n // It's important - for performance reasons - that all of this class's\n // members are initialized and that they are always initialized in the same\n // order. This will ensure that all OperatorSubscriber instances have the\n // same hidden class in V8. This, in turn, will help keep the number of\n // hidden classes involved in property accesses within the base class as\n // low as possible. If the number of hidden classes involved exceeds four,\n // the property accesses will become megamorphic and performance penalties\n // will be incurred - i.e. inline caches won't be used.\n //\n // The reasons for ensuring all instances have the same hidden class are\n // further discussed in this blog post from Benedikt Meurer:\n // https://benediktmeurer.de/2018/03/23/impact-of-polymorphism-on-component-based-frameworks-like-react/\n super(destination);\n this._next = onNext\n ? function (this: OperatorSubscriber, value: T) {\n try {\n onNext(value);\n } catch (err) {\n destination.error(err);\n }\n }\n : super._next;\n this._error = onError\n ? function (this: OperatorSubscriber, err: any) {\n try {\n onError(err);\n } catch (err) {\n // Send any errors that occur down stream.\n destination.error(err);\n } finally {\n // Ensure finalization.\n this.unsubscribe();\n }\n }\n : super._error;\n this._complete = onComplete\n ? function (this: OperatorSubscriber) {\n try {\n onComplete();\n } catch (err) {\n // Send any errors that occur down stream.\n destination.error(err);\n } finally {\n // Ensure finalization.\n this.unsubscribe();\n }\n }\n : super._complete;\n }\n\n unsubscribe() {\n if (!this.shouldUnsubscribe || this.shouldUnsubscribe()) {\n const { closed } = this;\n super.unsubscribe();\n // Execute additional teardown if we have any and we didn't already do so.\n !closed && this.onFinalize?.();\n }\n }\n}\n", "import { Subscription } from '../Subscription';\n\ninterface AnimationFrameProvider {\n schedule(callback: FrameRequestCallback): Subscription;\n requestAnimationFrame: typeof requestAnimationFrame;\n cancelAnimationFrame: typeof cancelAnimationFrame;\n delegate:\n | {\n requestAnimationFrame: typeof requestAnimationFrame;\n cancelAnimationFrame: typeof cancelAnimationFrame;\n }\n | undefined;\n}\n\nexport const animationFrameProvider: AnimationFrameProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n schedule(callback) {\n let request = requestAnimationFrame;\n let cancel: typeof cancelAnimationFrame | undefined = cancelAnimationFrame;\n const { delegate } = animationFrameProvider;\n if (delegate) {\n request = delegate.requestAnimationFrame;\n cancel = delegate.cancelAnimationFrame;\n }\n const handle = request((timestamp) => {\n // Clear the cancel function. The request has been fulfilled, so\n // attempting to cancel the request upon unsubscription would be\n // pointless.\n cancel = undefined;\n callback(timestamp);\n });\n return new Subscription(() => cancel?.(handle));\n },\n requestAnimationFrame(...args) {\n const { delegate } = animationFrameProvider;\n return (delegate?.requestAnimationFrame || requestAnimationFrame)(...args);\n },\n cancelAnimationFrame(...args) {\n const { delegate } = animationFrameProvider;\n return (delegate?.cancelAnimationFrame || cancelAnimationFrame)(...args);\n },\n delegate: undefined,\n};\n", "import { createErrorClass } from './createErrorClass';\n\nexport interface ObjectUnsubscribedError extends Error {}\n\nexport interface ObjectUnsubscribedErrorCtor {\n /**\n * @deprecated Internal implementation detail. Do not construct error instances.\n * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269\n */\n new (): ObjectUnsubscribedError;\n}\n\n/**\n * An error thrown when an action is invalid because the object has been\n * unsubscribed.\n *\n * @see {@link Subject}\n * @see {@link BehaviorSubject}\n *\n * @class ObjectUnsubscribedError\n */\nexport const ObjectUnsubscribedError: ObjectUnsubscribedErrorCtor = createErrorClass(\n (_super) =>\n function ObjectUnsubscribedErrorImpl(this: any) {\n _super(this);\n this.name = 'ObjectUnsubscribedError';\n this.message = 'object unsubscribed';\n }\n);\n", "import { Operator } from './Operator';\nimport { Observable } from './Observable';\nimport { Subscriber } from './Subscriber';\nimport { Subscription, EMPTY_SUBSCRIPTION } from './Subscription';\nimport { Observer, SubscriptionLike, TeardownLogic } from './types';\nimport { ObjectUnsubscribedError } from './util/ObjectUnsubscribedError';\nimport { arrRemove } from './util/arrRemove';\nimport { errorContext } from './util/errorContext';\n\n/**\n * A Subject is a special type of Observable that allows values to be\n * multicasted to many Observers. Subjects are like EventEmitters.\n *\n * Every Subject is an Observable and an Observer. You can subscribe to a\n * Subject, and you can call next to feed values as well as error and complete.\n */\nexport class Subject extends Observable implements SubscriptionLike {\n closed = false;\n\n private currentObservers: Observer[] | null = null;\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n observers: Observer[] = [];\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n isStopped = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n hasError = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n thrownError: any = null;\n\n /**\n * Creates a \"subject\" by basically gluing an observer to an observable.\n *\n * @deprecated Recommended you do not use. Will be removed at some point in the future. Plans for replacement still under discussion.\n */\n static create: (...args: any[]) => any = (destination: Observer, source: Observable): AnonymousSubject => {\n return new AnonymousSubject(destination, source);\n };\n\n constructor() {\n // NOTE: This must be here to obscure Observable's constructor.\n super();\n }\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n lift(operator: Operator): Observable {\n const subject = new AnonymousSubject(this, this);\n subject.operator = operator as any;\n return subject as any;\n }\n\n /** @internal */\n protected _throwIfClosed() {\n if (this.closed) {\n throw new ObjectUnsubscribedError();\n }\n }\n\n next(value: T) {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n if (!this.currentObservers) {\n this.currentObservers = Array.from(this.observers);\n }\n for (const observer of this.currentObservers) {\n observer.next(value);\n }\n }\n });\n }\n\n error(err: any) {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n this.hasError = this.isStopped = true;\n this.thrownError = err;\n const { observers } = this;\n while (observers.length) {\n observers.shift()!.error(err);\n }\n }\n });\n }\n\n complete() {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n this.isStopped = true;\n const { observers } = this;\n while (observers.length) {\n observers.shift()!.complete();\n }\n }\n });\n }\n\n unsubscribe() {\n this.isStopped = this.closed = true;\n this.observers = this.currentObservers = null!;\n }\n\n get observed() {\n return this.observers?.length > 0;\n }\n\n /** @internal */\n protected _trySubscribe(subscriber: Subscriber): TeardownLogic {\n this._throwIfClosed();\n return super._trySubscribe(subscriber);\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n this._throwIfClosed();\n this._checkFinalizedStatuses(subscriber);\n return this._innerSubscribe(subscriber);\n }\n\n /** @internal */\n protected _innerSubscribe(subscriber: Subscriber) {\n const { hasError, isStopped, observers } = this;\n if (hasError || isStopped) {\n return EMPTY_SUBSCRIPTION;\n }\n this.currentObservers = null;\n observers.push(subscriber);\n return new Subscription(() => {\n this.currentObservers = null;\n arrRemove(observers, subscriber);\n });\n }\n\n /** @internal */\n protected _checkFinalizedStatuses(subscriber: Subscriber) {\n const { hasError, thrownError, isStopped } = this;\n if (hasError) {\n subscriber.error(thrownError);\n } else if (isStopped) {\n subscriber.complete();\n }\n }\n\n /**\n * Creates a new Observable with this Subject as the source. You can do this\n * to create custom Observer-side logic of the Subject and conceal it from\n * code that uses the Observable.\n * @return Observable that this Subject casts to.\n */\n asObservable(): Observable {\n const observable: any = new Observable();\n observable.source = this;\n return observable;\n }\n}\n\nexport class AnonymousSubject extends Subject {\n constructor(\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n public destination?: Observer,\n source?: Observable\n ) {\n super();\n this.source = source;\n }\n\n next(value: T) {\n this.destination?.next?.(value);\n }\n\n error(err: any) {\n this.destination?.error?.(err);\n }\n\n complete() {\n this.destination?.complete?.();\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n return this.source?.subscribe(subscriber) ?? EMPTY_SUBSCRIPTION;\n }\n}\n", "import { Subject } from './Subject';\nimport { Subscriber } from './Subscriber';\nimport { Subscription } from './Subscription';\n\n/**\n * A variant of Subject that requires an initial value and emits its current\n * value whenever it is subscribed to.\n */\nexport class BehaviorSubject extends Subject {\n constructor(private _value: T) {\n super();\n }\n\n get value(): T {\n return this.getValue();\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n const subscription = super._subscribe(subscriber);\n !subscription.closed && subscriber.next(this._value);\n return subscription;\n }\n\n getValue(): T {\n const { hasError, thrownError, _value } = this;\n if (hasError) {\n throw thrownError;\n }\n this._throwIfClosed();\n return _value;\n }\n\n next(value: T): void {\n super.next((this._value = value));\n }\n}\n", "import { TimestampProvider } from '../types';\n\ninterface DateTimestampProvider extends TimestampProvider {\n delegate: TimestampProvider | undefined;\n}\n\nexport const dateTimestampProvider: DateTimestampProvider = {\n now() {\n // Use the variable rather than `this` so that the function can be called\n // without being bound to the provider.\n return (dateTimestampProvider.delegate || Date).now();\n },\n delegate: undefined,\n};\n", "import { Subject } from './Subject';\nimport { TimestampProvider } from './types';\nimport { Subscriber } from './Subscriber';\nimport { Subscription } from './Subscription';\nimport { dateTimestampProvider } from './scheduler/dateTimestampProvider';\n\n/**\n * A variant of {@link Subject} that \"replays\" old values to new subscribers by emitting them when they first subscribe.\n *\n * `ReplaySubject` has an internal buffer that will store a specified number of values that it has observed. Like `Subject`,\n * `ReplaySubject` \"observes\" values by having them passed to its `next` method. When it observes a value, it will store that\n * value for a time determined by the configuration of the `ReplaySubject`, as passed to its constructor.\n *\n * When a new subscriber subscribes to the `ReplaySubject` instance, it will synchronously emit all values in its buffer in\n * a First-In-First-Out (FIFO) manner. The `ReplaySubject` will also complete, if it has observed completion; and it will\n * error if it has observed an error.\n *\n * There are two main configuration items to be concerned with:\n *\n * 1. `bufferSize` - This will determine how many items are stored in the buffer, defaults to infinite.\n * 2. `windowTime` - The amount of time to hold a value in the buffer before removing it from the buffer.\n *\n * Both configurations may exist simultaneously. So if you would like to buffer a maximum of 3 values, as long as the values\n * are less than 2 seconds old, you could do so with a `new ReplaySubject(3, 2000)`.\n *\n * ### Differences with BehaviorSubject\n *\n * `BehaviorSubject` is similar to `new ReplaySubject(1)`, with a couple of exceptions:\n *\n * 1. `BehaviorSubject` comes \"primed\" with a single value upon construction.\n * 2. `ReplaySubject` will replay values, even after observing an error, where `BehaviorSubject` will not.\n *\n * @see {@link Subject}\n * @see {@link BehaviorSubject}\n * @see {@link shareReplay}\n */\nexport class ReplaySubject extends Subject {\n private _buffer: (T | number)[] = [];\n private _infiniteTimeWindow = true;\n\n /**\n * @param _bufferSize The size of the buffer to replay on subscription\n * @param _windowTime The amount of time the buffered items will stay buffered\n * @param _timestampProvider An object with a `now()` method that provides the current timestamp. This is used to\n * calculate the amount of time something has been buffered.\n */\n constructor(\n private _bufferSize = Infinity,\n private _windowTime = Infinity,\n private _timestampProvider: TimestampProvider = dateTimestampProvider\n ) {\n super();\n this._infiniteTimeWindow = _windowTime === Infinity;\n this._bufferSize = Math.max(1, _bufferSize);\n this._windowTime = Math.max(1, _windowTime);\n }\n\n next(value: T): void {\n const { isStopped, _buffer, _infiniteTimeWindow, _timestampProvider, _windowTime } = this;\n if (!isStopped) {\n _buffer.push(value);\n !_infiniteTimeWindow && _buffer.push(_timestampProvider.now() + _windowTime);\n }\n this._trimBuffer();\n super.next(value);\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n this._throwIfClosed();\n this._trimBuffer();\n\n const subscription = this._innerSubscribe(subscriber);\n\n const { _infiniteTimeWindow, _buffer } = this;\n // We use a copy here, so reentrant code does not mutate our array while we're\n // emitting it to a new subscriber.\n const copy = _buffer.slice();\n for (let i = 0; i < copy.length && !subscriber.closed; i += _infiniteTimeWindow ? 1 : 2) {\n subscriber.next(copy[i] as T);\n }\n\n this._checkFinalizedStatuses(subscriber);\n\n return subscription;\n }\n\n private _trimBuffer() {\n const { _bufferSize, _timestampProvider, _buffer, _infiniteTimeWindow } = this;\n // If we don't have an infinite buffer size, and we're over the length,\n // use splice to truncate the old buffer values off. Note that we have to\n // double the size for instances where we're not using an infinite time window\n // because we're storing the values and the timestamps in the same array.\n const adjustedBufferSize = (_infiniteTimeWindow ? 1 : 2) * _bufferSize;\n _bufferSize < Infinity && adjustedBufferSize < _buffer.length && _buffer.splice(0, _buffer.length - adjustedBufferSize);\n\n // Now, if we're not in an infinite time window, remove all values where the time is\n // older than what is allowed.\n if (!_infiniteTimeWindow) {\n const now = _timestampProvider.now();\n let last = 0;\n // Search the array for the first timestamp that isn't expired and\n // truncate the buffer up to that point.\n for (let i = 1; i < _buffer.length && (_buffer[i] as number) <= now; i += 2) {\n last = i;\n }\n last && _buffer.splice(0, last + 1);\n }\n }\n}\n", "import { Scheduler } from '../Scheduler';\nimport { Subscription } from '../Subscription';\nimport { SchedulerAction } from '../types';\n\n/**\n * A unit of work to be executed in a `scheduler`. An action is typically\n * created from within a {@link SchedulerLike} and an RxJS user does not need to concern\n * themselves about creating and manipulating an Action.\n *\n * ```ts\n * class Action extends Subscription {\n * new (scheduler: Scheduler, work: (state?: T) => void);\n * schedule(state?: T, delay: number = 0): Subscription;\n * }\n * ```\n */\nexport class Action extends Subscription {\n constructor(scheduler: Scheduler, work: (this: SchedulerAction, state?: T) => void) {\n super();\n }\n /**\n * Schedules this action on its parent {@link SchedulerLike} for execution. May be passed\n * some context object, `state`. May happen at some point in the future,\n * according to the `delay` parameter, if specified.\n * @param state Some contextual data that the `work` function uses when called by the\n * Scheduler.\n * @param delay Time to wait before executing the work, where the time unit is implicit\n * and defined by the Scheduler.\n * @return A subscription in order to be able to unsubscribe the scheduled work.\n */\n public schedule(state?: T, delay: number = 0): Subscription {\n return this;\n }\n}\n", "import type { TimerHandle } from './timerHandle';\ntype SetIntervalFunction = (handler: () => void, timeout?: number, ...args: any[]) => TimerHandle;\ntype ClearIntervalFunction = (handle: TimerHandle) => void;\n\ninterface IntervalProvider {\n setInterval: SetIntervalFunction;\n clearInterval: ClearIntervalFunction;\n delegate:\n | {\n setInterval: SetIntervalFunction;\n clearInterval: ClearIntervalFunction;\n }\n | undefined;\n}\n\nexport const intervalProvider: IntervalProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n setInterval(handler: () => void, timeout?: number, ...args) {\n const { delegate } = intervalProvider;\n if (delegate?.setInterval) {\n return delegate.setInterval(handler, timeout, ...args);\n }\n return setInterval(handler, timeout, ...args);\n },\n clearInterval(handle) {\n const { delegate } = intervalProvider;\n return (delegate?.clearInterval || clearInterval)(handle as any);\n },\n delegate: undefined,\n};\n", "import { Action } from './Action';\nimport { SchedulerAction } from '../types';\nimport { Subscription } from '../Subscription';\nimport { AsyncScheduler } from './AsyncScheduler';\nimport { intervalProvider } from './intervalProvider';\nimport { arrRemove } from '../util/arrRemove';\nimport { TimerHandle } from './timerHandle';\n\nexport class AsyncAction extends Action {\n public id: TimerHandle | undefined;\n public state?: T;\n // @ts-ignore: Property has no initializer and is not definitely assigned\n public delay: number;\n protected pending: boolean = false;\n\n constructor(protected scheduler: AsyncScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n public schedule(state?: T, delay: number = 0): Subscription {\n if (this.closed) {\n return this;\n }\n\n // Always replace the current state with the new state.\n this.state = state;\n\n const id = this.id;\n const scheduler = this.scheduler;\n\n //\n // Important implementation note:\n //\n // Actions only execute once by default, unless rescheduled from within the\n // scheduled callback. This allows us to implement single and repeat\n // actions via the same code path, without adding API surface area, as well\n // as mimic traditional recursion but across asynchronous boundaries.\n //\n // However, JS runtimes and timers distinguish between intervals achieved by\n // serial `setTimeout` calls vs. a single `setInterval` call. An interval of\n // serial `setTimeout` calls can be individually delayed, which delays\n // scheduling the next `setTimeout`, and so on. `setInterval` attempts to\n // guarantee the interval callback will be invoked more precisely to the\n // interval period, regardless of load.\n //\n // Therefore, we use `setInterval` to schedule single and repeat actions.\n // If the action reschedules itself with the same delay, the interval is not\n // canceled. If the action doesn't reschedule, or reschedules with a\n // different delay, the interval will be canceled after scheduled callback\n // execution.\n //\n if (id != null) {\n this.id = this.recycleAsyncId(scheduler, id, delay);\n }\n\n // Set the pending flag indicating that this action has been scheduled, or\n // has recursively rescheduled itself.\n this.pending = true;\n\n this.delay = delay;\n // If this action has already an async Id, don't request a new one.\n this.id = this.id ?? this.requestAsyncId(scheduler, this.id, delay);\n\n return this;\n }\n\n protected requestAsyncId(scheduler: AsyncScheduler, _id?: TimerHandle, delay: number = 0): TimerHandle {\n return intervalProvider.setInterval(scheduler.flush.bind(scheduler, this), delay);\n }\n\n protected recycleAsyncId(_scheduler: AsyncScheduler, id?: TimerHandle, delay: number | null = 0): TimerHandle | undefined {\n // If this action is rescheduled with the same delay time, don't clear the interval id.\n if (delay != null && this.delay === delay && this.pending === false) {\n return id;\n }\n // Otherwise, if the action's delay time is different from the current delay,\n // or the action has been rescheduled before it's executed, clear the interval id\n if (id != null) {\n intervalProvider.clearInterval(id);\n }\n\n return undefined;\n }\n\n /**\n * Immediately executes this action and the `work` it contains.\n */\n public execute(state: T, delay: number): any {\n if (this.closed) {\n return new Error('executing a cancelled action');\n }\n\n this.pending = false;\n const error = this._execute(state, delay);\n if (error) {\n return error;\n } else if (this.pending === false && this.id != null) {\n // Dequeue if the action didn't reschedule itself. Don't call\n // unsubscribe(), because the action could reschedule later.\n // For example:\n // ```\n // scheduler.schedule(function doWork(counter) {\n // /* ... I'm a busy worker bee ... */\n // var originalAction = this;\n // /* wait 100ms before rescheduling the action */\n // setTimeout(function () {\n // originalAction.schedule(counter + 1);\n // }, 100);\n // }, 1000);\n // ```\n this.id = this.recycleAsyncId(this.scheduler, this.id, null);\n }\n }\n\n protected _execute(state: T, _delay: number): any {\n let errored: boolean = false;\n let errorValue: any;\n try {\n this.work(state);\n } catch (e) {\n errored = true;\n // HACK: Since code elsewhere is relying on the \"truthiness\" of the\n // return here, we can't have it return \"\" or 0 or false.\n // TODO: Clean this up when we refactor schedulers mid-version-8 or so.\n errorValue = e ? e : new Error('Scheduled action threw falsy error');\n }\n if (errored) {\n this.unsubscribe();\n return errorValue;\n }\n }\n\n unsubscribe() {\n if (!this.closed) {\n const { id, scheduler } = this;\n const { actions } = scheduler;\n\n this.work = this.state = this.scheduler = null!;\n this.pending = false;\n\n arrRemove(actions, this);\n if (id != null) {\n this.id = this.recycleAsyncId(scheduler, id, null);\n }\n\n this.delay = null!;\n super.unsubscribe();\n }\n }\n}\n", "import { Action } from './scheduler/Action';\nimport { Subscription } from './Subscription';\nimport { SchedulerLike, SchedulerAction } from './types';\nimport { dateTimestampProvider } from './scheduler/dateTimestampProvider';\n\n/**\n * An execution context and a data structure to order tasks and schedule their\n * execution. Provides a notion of (potentially virtual) time, through the\n * `now()` getter method.\n *\n * Each unit of work in a Scheduler is called an `Action`.\n *\n * ```ts\n * class Scheduler {\n * now(): number;\n * schedule(work, delay?, state?): Subscription;\n * }\n * ```\n *\n * @deprecated Scheduler is an internal implementation detail of RxJS, and\n * should not be used directly. Rather, create your own class and implement\n * {@link SchedulerLike}. Will be made internal in v8.\n */\nexport class Scheduler implements SchedulerLike {\n public static now: () => number = dateTimestampProvider.now;\n\n constructor(private schedulerActionCtor: typeof Action, now: () => number = Scheduler.now) {\n this.now = now;\n }\n\n /**\n * A getter method that returns a number representing the current time\n * (at the time this function was called) according to the scheduler's own\n * internal clock.\n * @return A number that represents the current time. May or may not\n * have a relation to wall-clock time. May or may not refer to a time unit\n * (e.g. milliseconds).\n */\n public now: () => number;\n\n /**\n * Schedules a function, `work`, for execution. May happen at some point in\n * the future, according to the `delay` parameter, if specified. May be passed\n * some context object, `state`, which will be passed to the `work` function.\n *\n * The given arguments will be processed an stored as an Action object in a\n * queue of actions.\n *\n * @param work A function representing a task, or some unit of work to be\n * executed by the Scheduler.\n * @param delay Time to wait before executing the work, where the time unit is\n * implicit and defined by the Scheduler itself.\n * @param state Some contextual data that the `work` function uses when called\n * by the Scheduler.\n * @return A subscription in order to be able to unsubscribe the scheduled work.\n */\n public schedule(work: (this: SchedulerAction, state?: T) => void, delay: number = 0, state?: T): Subscription {\n return new this.schedulerActionCtor(this, work).schedule(state, delay);\n }\n}\n", "import { Scheduler } from '../Scheduler';\nimport { Action } from './Action';\nimport { AsyncAction } from './AsyncAction';\nimport { TimerHandle } from './timerHandle';\n\nexport class AsyncScheduler extends Scheduler {\n public actions: Array> = [];\n /**\n * A flag to indicate whether the Scheduler is currently executing a batch of\n * queued actions.\n * @internal\n */\n public _active: boolean = false;\n /**\n * An internal ID used to track the latest asynchronous task such as those\n * coming from `setTimeout`, `setInterval`, `requestAnimationFrame`, and\n * others.\n * @internal\n */\n public _scheduled: TimerHandle | undefined;\n\n constructor(SchedulerAction: typeof Action, now: () => number = Scheduler.now) {\n super(SchedulerAction, now);\n }\n\n public flush(action: AsyncAction): void {\n const { actions } = this;\n\n if (this._active) {\n actions.push(action);\n return;\n }\n\n let error: any;\n this._active = true;\n\n do {\n if ((error = action.execute(action.state, action.delay))) {\n break;\n }\n } while ((action = actions.shift()!)); // exhaust the scheduler queue\n\n this._active = false;\n\n if (error) {\n while ((action = actions.shift()!)) {\n action.unsubscribe();\n }\n throw error;\n }\n }\n}\n", "import { AsyncAction } from './AsyncAction';\nimport { AsyncScheduler } from './AsyncScheduler';\n\n/**\n *\n * Async Scheduler\n *\n * Schedule task as if you used setTimeout(task, duration)\n *\n * `async` scheduler schedules tasks asynchronously, by putting them on the JavaScript\n * event loop queue. It is best used to delay tasks in time or to schedule tasks repeating\n * in intervals.\n *\n * If you just want to \"defer\" task, that is to perform it right after currently\n * executing synchronous code ends (commonly achieved by `setTimeout(deferredTask, 0)`),\n * better choice will be the {@link asapScheduler} scheduler.\n *\n * ## Examples\n * Use async scheduler to delay task\n * ```ts\n * import { asyncScheduler } from 'rxjs';\n *\n * const task = () => console.log('it works!');\n *\n * asyncScheduler.schedule(task, 2000);\n *\n * // After 2 seconds logs:\n * // \"it works!\"\n * ```\n *\n * Use async scheduler to repeat task in intervals\n * ```ts\n * import { asyncScheduler } from 'rxjs';\n *\n * function task(state) {\n * console.log(state);\n * this.schedule(state + 1, 1000); // `this` references currently executing Action,\n * // which we reschedule with new state and delay\n * }\n *\n * asyncScheduler.schedule(task, 3000, 0);\n *\n * // Logs:\n * // 0 after 3s\n * // 1 after 4s\n * // 2 after 5s\n * // 3 after 6s\n * ```\n */\n\nexport const asyncScheduler = new AsyncScheduler(AsyncAction);\n\n/**\n * @deprecated Renamed to {@link asyncScheduler}. Will be removed in v8.\n */\nexport const async = asyncScheduler;\n", "import { AsyncAction } from './AsyncAction';\nimport { Subscription } from '../Subscription';\nimport { QueueScheduler } from './QueueScheduler';\nimport { SchedulerAction } from '../types';\nimport { TimerHandle } from './timerHandle';\n\nexport class QueueAction extends AsyncAction {\n constructor(protected scheduler: QueueScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n public schedule(state?: T, delay: number = 0): Subscription {\n if (delay > 0) {\n return super.schedule(state, delay);\n }\n this.delay = delay;\n this.state = state;\n this.scheduler.flush(this);\n return this;\n }\n\n public execute(state: T, delay: number): any {\n return delay > 0 || this.closed ? super.execute(state, delay) : this._execute(state, delay);\n }\n\n protected requestAsyncId(scheduler: QueueScheduler, id?: TimerHandle, delay: number = 0): TimerHandle {\n // If delay exists and is greater than 0, or if the delay is null (the\n // action wasn't rescheduled) but was originally scheduled as an async\n // action, then recycle as an async action.\n\n if ((delay != null && delay > 0) || (delay == null && this.delay > 0)) {\n return super.requestAsyncId(scheduler, id, delay);\n }\n\n // Otherwise flush the scheduler starting with this action.\n scheduler.flush(this);\n\n // HACK: In the past, this was returning `void`. However, `void` isn't a valid\n // `TimerHandle`, and generally the return value here isn't really used. So the\n // compromise is to return `0` which is both \"falsy\" and a valid `TimerHandle`,\n // as opposed to refactoring every other instanceo of `requestAsyncId`.\n return 0;\n }\n}\n", "import { AsyncScheduler } from './AsyncScheduler';\n\nexport class QueueScheduler extends AsyncScheduler {\n}\n", "import { QueueAction } from './QueueAction';\nimport { QueueScheduler } from './QueueScheduler';\n\n/**\n *\n * Queue Scheduler\n *\n * Put every next task on a queue, instead of executing it immediately\n *\n * `queue` scheduler, when used with delay, behaves the same as {@link asyncScheduler} scheduler.\n *\n * When used without delay, it schedules given task synchronously - executes it right when\n * it is scheduled. However when called recursively, that is when inside the scheduled task,\n * another task is scheduled with queue scheduler, instead of executing immediately as well,\n * that task will be put on a queue and wait for current one to finish.\n *\n * This means that when you execute task with `queue` scheduler, you are sure it will end\n * before any other task scheduled with that scheduler will start.\n *\n * ## Examples\n * Schedule recursively first, then do something\n * ```ts\n * import { queueScheduler } from 'rxjs';\n *\n * queueScheduler.schedule(() => {\n * queueScheduler.schedule(() => console.log('second')); // will not happen now, but will be put on a queue\n *\n * console.log('first');\n * });\n *\n * // Logs:\n * // \"first\"\n * // \"second\"\n * ```\n *\n * Reschedule itself recursively\n * ```ts\n * import { queueScheduler } from 'rxjs';\n *\n * queueScheduler.schedule(function(state) {\n * if (state !== 0) {\n * console.log('before', state);\n * this.schedule(state - 1); // `this` references currently executing Action,\n * // which we reschedule with new state\n * console.log('after', state);\n * }\n * }, 0, 3);\n *\n * // In scheduler that runs recursively, you would expect:\n * // \"before\", 3\n * // \"before\", 2\n * // \"before\", 1\n * // \"after\", 1\n * // \"after\", 2\n * // \"after\", 3\n *\n * // But with queue it logs:\n * // \"before\", 3\n * // \"after\", 3\n * // \"before\", 2\n * // \"after\", 2\n * // \"before\", 1\n * // \"after\", 1\n * ```\n */\n\nexport const queueScheduler = new QueueScheduler(QueueAction);\n\n/**\n * @deprecated Renamed to {@link queueScheduler}. Will be removed in v8.\n */\nexport const queue = queueScheduler;\n", "import { AsyncAction } from './AsyncAction';\nimport { AnimationFrameScheduler } from './AnimationFrameScheduler';\nimport { SchedulerAction } from '../types';\nimport { animationFrameProvider } from './animationFrameProvider';\nimport { TimerHandle } from './timerHandle';\n\nexport class AnimationFrameAction extends AsyncAction {\n constructor(protected scheduler: AnimationFrameScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n protected requestAsyncId(scheduler: AnimationFrameScheduler, id?: TimerHandle, delay: number = 0): TimerHandle {\n // If delay is greater than 0, request as an async action.\n if (delay !== null && delay > 0) {\n return super.requestAsyncId(scheduler, id, delay);\n }\n // Push the action to the end of the scheduler queue.\n scheduler.actions.push(this);\n // If an animation frame has already been requested, don't request another\n // one. If an animation frame hasn't been requested yet, request one. Return\n // the current animation frame request id.\n return scheduler._scheduled || (scheduler._scheduled = animationFrameProvider.requestAnimationFrame(() => scheduler.flush(undefined)));\n }\n\n protected recycleAsyncId(scheduler: AnimationFrameScheduler, id?: TimerHandle, delay: number = 0): TimerHandle | undefined {\n // If delay exists and is greater than 0, or if the delay is null (the\n // action wasn't rescheduled) but was originally scheduled as an async\n // action, then recycle as an async action.\n if (delay != null ? delay > 0 : this.delay > 0) {\n return super.recycleAsyncId(scheduler, id, delay);\n }\n // If the scheduler queue has no remaining actions with the same async id,\n // cancel the requested animation frame and set the scheduled flag to\n // undefined so the next AnimationFrameAction will request its own.\n const { actions } = scheduler;\n if (id != null && id === scheduler._scheduled && actions[actions.length - 1]?.id !== id) {\n animationFrameProvider.cancelAnimationFrame(id as number);\n scheduler._scheduled = undefined;\n }\n // Return undefined so the action knows to request a new async id if it's rescheduled.\n return undefined;\n }\n}\n", "import { AsyncAction } from './AsyncAction';\nimport { AsyncScheduler } from './AsyncScheduler';\n\nexport class AnimationFrameScheduler extends AsyncScheduler {\n public flush(action?: AsyncAction): void {\n this._active = true;\n // The async id that effects a call to flush is stored in _scheduled.\n // Before executing an action, it's necessary to check the action's async\n // id to determine whether it's supposed to be executed in the current\n // flush.\n // Previous implementations of this method used a count to determine this,\n // but that was unsound, as actions that are unsubscribed - i.e. cancelled -\n // are removed from the actions array and that can shift actions that are\n // scheduled to be executed in a subsequent flush into positions at which\n // they are executed within the current flush.\n let flushId;\n if (action) {\n flushId = action.id;\n } else {\n flushId = this._scheduled;\n this._scheduled = undefined;\n }\n\n const { actions } = this;\n let error: any;\n action = action || actions.shift()!;\n\n do {\n if ((error = action.execute(action.state, action.delay))) {\n break;\n }\n } while ((action = actions[0]) && action.id === flushId && actions.shift());\n\n this._active = false;\n\n if (error) {\n while ((action = actions[0]) && action.id === flushId && actions.shift()) {\n action.unsubscribe();\n }\n throw error;\n }\n }\n}\n", "import { AnimationFrameAction } from './AnimationFrameAction';\nimport { AnimationFrameScheduler } from './AnimationFrameScheduler';\n\n/**\n *\n * Animation Frame Scheduler\n *\n * Perform task when `window.requestAnimationFrame` would fire\n *\n * When `animationFrame` scheduler is used with delay, it will fall back to {@link asyncScheduler} scheduler\n * behaviour.\n *\n * Without delay, `animationFrame` scheduler can be used to create smooth browser animations.\n * It makes sure scheduled task will happen just before next browser content repaint,\n * thus performing animations as efficiently as possible.\n *\n * ## Example\n * Schedule div height animation\n * ```ts\n * // html:
\n * import { animationFrameScheduler } from 'rxjs';\n *\n * const div = document.querySelector('div');\n *\n * animationFrameScheduler.schedule(function(height) {\n * div.style.height = height + \"px\";\n *\n * this.schedule(height + 1); // `this` references currently executing Action,\n * // which we reschedule with new state\n * }, 0, 0);\n *\n * // You will see a div element growing in height\n * ```\n */\n\nexport const animationFrameScheduler = new AnimationFrameScheduler(AnimationFrameAction);\n\n/**\n * @deprecated Renamed to {@link animationFrameScheduler}. Will be removed in v8.\n */\nexport const animationFrame = animationFrameScheduler;\n", "import { Observable } from '../Observable';\nimport { SchedulerLike } from '../types';\n\n/**\n * A simple Observable that emits no items to the Observer and immediately\n * emits a complete notification.\n *\n * Just emits 'complete', and nothing else.\n *\n * ![](empty.png)\n *\n * A simple Observable that only emits the complete notification. It can be used\n * for composing with other Observables, such as in a {@link mergeMap}.\n *\n * ## Examples\n *\n * Log complete notification\n *\n * ```ts\n * import { EMPTY } from 'rxjs';\n *\n * EMPTY.subscribe({\n * next: () => console.log('Next'),\n * complete: () => console.log('Complete!')\n * });\n *\n * // Outputs\n * // Complete!\n * ```\n *\n * Emit the number 7, then complete\n *\n * ```ts\n * import { EMPTY, startWith } from 'rxjs';\n *\n * const result = EMPTY.pipe(startWith(7));\n * result.subscribe(x => console.log(x));\n *\n * // Outputs\n * // 7\n * ```\n *\n * Map and flatten only odd numbers to the sequence `'a'`, `'b'`, `'c'`\n *\n * ```ts\n * import { interval, mergeMap, of, EMPTY } from 'rxjs';\n *\n * const interval$ = interval(1000);\n * const result = interval$.pipe(\n * mergeMap(x => x % 2 === 1 ? of('a', 'b', 'c') : EMPTY),\n * );\n * result.subscribe(x => console.log(x));\n *\n * // Results in the following to the console:\n * // x is equal to the count on the interval, e.g. (0, 1, 2, 3, ...)\n * // x will occur every 1000ms\n * // if x % 2 is equal to 1, print a, b, c (each on its own)\n * // if x % 2 is not equal to 1, nothing will be output\n * ```\n *\n * @see {@link Observable}\n * @see {@link NEVER}\n * @see {@link of}\n * @see {@link throwError}\n */\nexport const EMPTY = new Observable((subscriber) => subscriber.complete());\n\n/**\n * @param scheduler A {@link SchedulerLike} to use for scheduling\n * the emission of the complete notification.\n * @deprecated Replaced with the {@link EMPTY} constant or {@link scheduled} (e.g. `scheduled([], scheduler)`). Will be removed in v8.\n */\nexport function empty(scheduler?: SchedulerLike) {\n return scheduler ? emptyScheduled(scheduler) : EMPTY;\n}\n\nfunction emptyScheduled(scheduler: SchedulerLike) {\n return new Observable((subscriber) => scheduler.schedule(() => subscriber.complete()));\n}\n", "import { SchedulerLike } from '../types';\nimport { isFunction } from './isFunction';\n\nexport function isScheduler(value: any): value is SchedulerLike {\n return value && isFunction(value.schedule);\n}\n", "import { SchedulerLike } from '../types';\nimport { isFunction } from './isFunction';\nimport { isScheduler } from './isScheduler';\n\nfunction last(arr: T[]): T | undefined {\n return arr[arr.length - 1];\n}\n\nexport function popResultSelector(args: any[]): ((...args: unknown[]) => unknown) | undefined {\n return isFunction(last(args)) ? args.pop() : undefined;\n}\n\nexport function popScheduler(args: any[]): SchedulerLike | undefined {\n return isScheduler(last(args)) ? args.pop() : undefined;\n}\n\nexport function popNumber(args: any[], defaultValue: number): number {\n return typeof last(args) === 'number' ? args.pop()! : defaultValue;\n}\n", "export const isArrayLike = ((x: any): x is ArrayLike => x && typeof x.length === 'number' && typeof x !== 'function');", "import { isFunction } from \"./isFunction\";\n\n/**\n * Tests to see if the object is \"thennable\".\n * @param value the object to test\n */\nexport function isPromise(value: any): value is PromiseLike {\n return isFunction(value?.then);\n}\n", "import { InteropObservable } from '../types';\nimport { observable as Symbol_observable } from '../symbol/observable';\nimport { isFunction } from './isFunction';\n\n/** Identifies an input as being Observable (but not necessary an Rx Observable) */\nexport function isInteropObservable(input: any): input is InteropObservable {\n return isFunction(input[Symbol_observable]);\n}\n", "import { isFunction } from './isFunction';\n\nexport function isAsyncIterable(obj: any): obj is AsyncIterable {\n return Symbol.asyncIterator && isFunction(obj?.[Symbol.asyncIterator]);\n}\n", "/**\n * Creates the TypeError to throw if an invalid object is passed to `from` or `scheduled`.\n * @param input The object that was passed.\n */\nexport function createInvalidObservableTypeError(input: any) {\n // TODO: We should create error codes that can be looked up, so this can be less verbose.\n return new TypeError(\n `You provided ${\n input !== null && typeof input === 'object' ? 'an invalid object' : `'${input}'`\n } where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.`\n );\n}\n", "export function getSymbolIterator(): symbol {\n if (typeof Symbol !== 'function' || !Symbol.iterator) {\n return '@@iterator' as any;\n }\n\n return Symbol.iterator;\n}\n\nexport const iterator = getSymbolIterator();\n", "import { iterator as Symbol_iterator } from '../symbol/iterator';\nimport { isFunction } from './isFunction';\n\n/** Identifies an input as being an Iterable */\nexport function isIterable(input: any): input is Iterable {\n return isFunction(input?.[Symbol_iterator]);\n}\n", "import { ReadableStreamLike } from '../types';\nimport { isFunction } from './isFunction';\n\nexport async function* readableStreamLikeToAsyncGenerator(readableStream: ReadableStreamLike): AsyncGenerator {\n const reader = readableStream.getReader();\n try {\n while (true) {\n const { value, done } = await reader.read();\n if (done) {\n return;\n }\n yield value!;\n }\n } finally {\n reader.releaseLock();\n }\n}\n\nexport function isReadableStreamLike(obj: any): obj is ReadableStreamLike {\n // We don't want to use instanceof checks because they would return\n // false for instances from another Realm, like an