Skip to content

README.md

Latest commit

 

History

History
200 lines (152 loc) · 8.25 KB

README.md

File metadata and controls

200 lines (152 loc) · 8.25 KB
Raw

BlazorWebForms

Structured form collection for Blazor applications.
Define forms as data, collect submissions, run approval submission workflows, and export results.

License: AGPL-3.0 .NET 10 NuGet Ask DeepWiki

What is BlazorWebForms?

BlazorWebForms is a library that lets you define forms as structured data (FormDefinition), render them dynamically, and collect submissions with full workflow support.

Packages

Package Purpose
BlazorWebForms.Core Domain models, FormsApplicationService, all interfaces
BlazorWebForms.Infrastructure.SqlServer EF Core persistence (SQL Server/Azure SQL), file storage, email (SMTP, SendGrid, Graph), data export

Architecture

Your Blazor App
      │
      ▼
FormsApplicationService          ← single entry point for all operations
      │
      ├── IFormsRepository       ← persistence (implemented by Infrastructure.SqlServer)
      ├── IFileStorage           ← file storage (local disk or bring your own)
      ├── IEmailNotifier         ← email (SMTP / SendGrid / Graph / no-op)
      ├── IPermissionEvaluator   ← role-based access (override for custom rules)
      ├── ICurrentUserContext    ← who is logged in (you implement this)
      └── ICustomFieldHandler[]  ← optional: register your own field types

Core has no dependency on any database, email provider, or UI framework. Every integration point is an interface you can swap.

Quick Start

1. Install packages

dotnet add package BlazorWebForms.Core
dotnet add package BlazorWebForms.Infrastructure.SqlServer

2. Register services

// Program.cs
builder.Services.AddBlazorWebFormsCore();

builder.Services.AddBlazorWebFormsSqlServer(opt =>
{
    opt.ConnectionString = builder.Configuration.GetConnectionString("BlazorWebForms")!;
    opt.StorageRoot = Path.Combine(builder.Environment.ContentRootPath, "uploads");
});

// Required: tell the service who the current user is
builder.Services.AddScoped<ICurrentUserContext, YourCurrentUserContext>();

3. Apply database schema

On first run, call SeedAsync to create tables automatically:

await app.Services.GetRequiredService<FormsApplicationService>().SeedAsync();

Or generate a migration script for review before applying:

dotnet ef migrations script \
  --project src/BlazorWebForms.Infrastructure.SqlServer \
  --startup-project src/BlazorWebForms.SampleApp

4. Create and publish a form

var draft = await formsService.SaveDraftAsync(new SaveDraftRequest
{
    Name = "Travel Request",
    Slug = "travel-request",
    Definition = new FormDefinition
    {
        DefaultCulture = "en-US",
        Sections =
        [
            new FormSectionDefinition
            {
                Title = "Trip Details",
                Fields =
                [
                    new FormFieldDefinition { Id = "destination", Label = "Destination", Kind = FormFieldKind.Text, Required = true },
                    new FormFieldDefinition { Id = "depart-date", Label = "Departure date", Kind = FormFieldKind.Date, Required = true },
                    new FormFieldDefinition { Id = "reason",      Label = "Reason",         Kind = FormFieldKind.TextArea }
                ]
            }
        ]
    }
});

await formsService.PublishAsync(draft.Id);

5. Accept a submission

var entry = await formsService.SubmitEntryAsync(formId, new SubmitEntryRequest
{
    Answers = new() { ["destination"] = "Paris", ["depart-date"] = "2026-09-01" },
    Approvers = [new ApproverInput { Id = "E-1042", DisplayName = "Jane Smith", Email = "jane@example.com" }]
});

Feature Overview

Forms

  • 15 built-in field types: Text, TextArea, Number, Select, Radio, Checkbox, Date, File, RichText, Signature, RepeatableList, RankedChoice, MatrixSingle, MatrixMulti, and Custom (bring your own)
  • Visibility conditions: Show/hide sections and fields using AND/OR rules against other field values
  • Localization: Per-field/section/option localized labels with culture fallback chain
  • Branding: Logo, hero image, accent color, button radius, surface color per form
  • Metadata bags: Attach arbitrary Dictionary<string, string> to forms, sections, and fields
  • Schema versioning: Definitions carry a SchemaVersion for forward-compatibility handling

Submissions

  • Draft flow: save, resume, and finalize multi-session drafts
  • Immutable revisions or overwrite-latest: Configurable per form
  • File uploads: Per-field constraints (size, MIME type, extension, file count)
  • Search indexing: Mark fields as Searchable; text index is maintained on save

Approvals

  • Sequential multi-step approval: Assigned approvers, ordered
  • Approve / reject / resubmit: Full state machine with server-side invariant enforcement
  • Audit trail: Every action is appended to an immutable ApprovalAuditEvent log
  • Approver identity: Id (employee ID), DisplayName, and Email on each step
  • Email notifications: Assignment, reminder, approval, rejection, and resubmit events

Infrastructure (SqlServer package)

  • EF Core 10: Persistence with SQL Server / Azure SQL
  • Idempotent schema bootstrap: SeedAsync applies column additions without a full migration runner
  • Local file storage: Safe filename normalization, SHA-256 hash, signed short-lived download links
  • Text PDF export: Structured entry export with configurable row/size limits
  • Email strategies: DryRun (default), Smtp, SendGrid, Graph (Microsoft 365)
  • Anti-abuse guards: Per-minute upload and notification rate limits
  • Draft cleanup: Background removal of stale drafts and orphaned files (configurable retention)
  • Operational telemetry: Upload/PDF/email counters via IOperationalTelemetry

Extensibility

  • Register custom field types with AddCustomFieldHandler<T>()
  • Override any default implementation (IPermissionEvaluator, IConditionEvaluator, IFileStorage, …)
  • Plug in prefill providers (IFormPrefillProvider) for claim-based, employee-based, or custom data

Documentation

Document Description
docs/USING_BlazorWebForms.md Integration guide: NuGet, local feed, ProjectReference
docs/CORE_MODELS.md Complete domain model reference
docs/CORE_API_REFERENCE.md Full FormsApplicationService API
docs/CORE_EXTENDING.md Implementing interfaces, auth examples, custom field types
docs/CORE_LOCALIZATION.md Localization, culture resolution, condition evaluation
docs/QUESTION_TYPES.md Every field kind with properties, validation, and examples
src/BlazorWebForms.Core/README.md Core package reference
src/BlazorWebForms.Infrastructure.SqlServer/README.md SQL Server package reference

Running Tests

# Core isolated unit tests
dotnet run --project tests/BlazorWebForms.Core.Tests -c Debug

# SQL Server integration tests (requires LocalDB)
dotnet run --project tests/BlazorWebForms.Infrastructure.SqlServer.Tests -c Debug

License

AGPL-3.0-only. Commercial licensing inquiries: open an issue.