Substantive.Blazor.DynamicForm

A Blazor library that renders nested object graphs as editable forms using FormCraft and MudBlazor.

Features

• Builds a deterministic FormNode tree from a model instance using reflection and DisplayAttribute metadata.
• Renders nested sections (root fields and child nodes) as independent FormCraft forms.
• Four layout modes: None (flattened inline), Tabs, Stepper, and Sidebar.
• Attribute-driven field configuration via AttributeFormBuilderExtensions.AddFieldsFromAttributesAndDisplayAttribute<TModel>().
• DefaultFormConfigurationProvider creates and caches FormCraft configurations per runtime type to avoid repeated reflection.
• Register a custom IFormConfigurationProvider via dependency injection to override the default configuration strategy.

Requirements

• .NET 10
• FormCraft and MudBlazor packages available in the consuming project.

Quick start

1. Add a project reference to this package or include the project in your solution.
2. Ensure FormCraft and MudBlazor are registered in your application.
3. Use NestedFormCraftComponent in a Razor page or component:

@using Substantive.Blazor.DynamicForm

<NestedFormCraftComponent TModel="MyModel"
                          Model="@model"
                          Layout="GroupLayout.Tabs"
                          ShowSubmitButton="true"
                          OnValidSubmit="HandleSubmit" />

@code {
    private MyModel model = new();

    private Task HandleSubmit(MyModel? m)
    {
        // called when any nested section submits successfully
        return Task.CompletedTask;
    }
}

Key component parameters

Layout modes

Field configuration with AddFieldsFromAttributesAndDisplayAttribute

AttributeFormBuilderExtensions.AddFieldsFromAttributesAndDisplayAttribute<TModel>() scans a model type for field attributes and builds the FormCraft field configuration automatically. It is called internally by DefaultFormConfigurationProvider, so no manual wiring is needed unless you build a custom provider.

Supported field attributes

Properties without one of the above field attributes are not rendered by FormCraft, even if they have a [Display] annotation.

Label and placeholder resolution

The extension follows a deterministic fallback order to keep UI text consistent:

• Label: DisplayAttribute.Name → field attribute's Label → property name.
• Placeholder / Prompt: DisplayAttribute.Prompt → field attribute's Placeholder.

Setting [Display(Name = "...")] on a property is therefore the cleanest way to control labels without coupling the attribute to a specific field type.

Validation attributes

The following standard System.ComponentModel.DataAnnotations attributes are applied automatically when present on the property:

Example

using System.ComponentModel.DataAnnotations;
using FormCraft;
using Substantive.Blazor.DynamicForm;

[Display(Name = "User Profile", Description = "Manage account details")]
public class UserProfileModel
{
    // Label comes from DisplayAttribute.Name; prompt from DisplayAttribute.Prompt
    [Display(Name = "Full Name", Prompt = "Enter your full name", Order = 1)]
    [TextField]
    [Required]
    [MaxLength(100)]
    public string? FullName { get; set; }

    // Label falls back to EmailFieldAttribute.Label because no DisplayAttribute.Name is set
    [EmailField(Label = "Email Address", Placeholder = "you@example.com", ValidateFormat = true)]
    [Required]
    public string? Email { get; set; }

    [Display(Name = "Age", Order = 3)]
    [NumberField(Min = 0, Max = 150)]
    [Range(0, 150, ErrorMessage = "Age must be between 0 and 150")]
    public int Age { get; set; }

    [Display(Name = "Bio", Order = 4)]
    [TextArea(Rows = 4, MaxLength = 500)]
    public string? Bio { get; set; }

    [Display(Name = "Country", Order = 5)]
    [SelectField(Options = ["Australia", "Canada", "United Kingdom", "United States"])]
    public string? Country { get; set; }

    [Display(Name = "Subscribe to newsletter", Order = 6)]
    [CheckboxField(Text = "Yes, send me updates")]
    public bool Newsletter { get; set; }

    // Not rendered — no field attribute present
    public string? InternalToken { get; set; }

    // Explicitly hidden from the form
    [Display(AutoGenerateField = false)]
    public string? AuditTrail { get; set; }

    // Complex property → becomes a child section (no field attribute needed)
    [Display(Name = "Address", Description = "Postal address details", Order = 7)]
    public AddressModel Address { get; set; } = new();
}

public class AddressModel
{
    [Display(Name = "Street", Order = 1)]
    [TextField]
    public string? Street { get; set; }

    [Display(Name = "City", Order = 2)]
    [TextField]
    public string? City { get; set; }

    [Display(Name = "Postal Code", Order = 3)]
    [TextField]
    [RegularExpression(@"^\d{4,10}$", ErrorMessage = "Enter a valid postal code")]
    public string? PostalCode { get; set; }
}

With Layout="GroupLayout.Tabs" this model produces two tabs — User Profile and Address — each rendered as an independent FormCraft form.

Configuration

Default (attribute-driven)

DefaultFormConfigurationProvider is used automatically when no IFormConfigurationProvider is registered in DI. It calls AttributeFormBuilderExtensions.AddFieldsFromAttributesAndDisplayAttribute<TModel>() to build a FormCraft configuration from your model's attributes and caches the result per type.

Custom provider via DI

Register an implementation of IFormConfigurationProvider in your service collection to control field layout, validation, and rendering for any model type:

builder.Services.AddSingleton<IFormConfigurationProvider, MyFormConfigurationProvider>();

NestedFormCraftComponent resolves the provider via [Inject] and falls back to DefaultFormConfigurationProvider when none is registered.

Model annotation with DisplayAttribute

DisplayAttribute is the primary way to control how the tree is built and how sections and fields appear in the UI.

AutoGenerateField = true is never required. NestedFormTreeBuilder includes a property when [Display] is absent or when AutoGenerateField is not explicitly set — GetAutoGenerateField() returns null in that case, which is treated as included. Only AutoGenerateField = false changes behaviour.

The DisplayAttribute on the root model type itself sets the title of the root section ("General" by default).

Example

using System.ComponentModel.DataAnnotations;

[Display(Name = "User Profile", Description = "Manage the user's account details")]
public class UserProfileModel
{
    [Display(Name = "Full Name", Order = 1)]
    public string? FullName { get; set; }

    [Display(Name = "Email Address", Order = 2)]
    public string? Email { get; set; }

    // Hidden from the form
    [Display(AutoGenerateField = false)]
    public string? InternalId { get; set; }

    // Complex property → becomes a child section titled "Address"
    [Display(Name = "Address", Description = "Postal address details", Order = 3)]
    public AddressModel Address { get; set; } = new();
}

public class AddressModel
{
    [Display(Name = "Street", Order = 1)]
    public string? Street { get; set; }

    [Display(Name = "City", Order = 2)]
    public string? City { get; set; }

    [Display(Name = "Postal Code", Order = 3)]
    public string? PostalCode { get; set; }
}

With the model above and Layout="GroupLayout.Tabs", the component renders two tabs — User Profile (root fields: Full Name, Email) and Address (Address child section) — in that order.

How it works

1. NestedFormTreeBuilder inspects the model type using reflection. Complex navigation properties become child FormNode entries; primitive or displayable properties at the root are collected into a synthetic RootFieldsNode titled "General".
2. NestedFormCraftComponent builds the tree on OnParametersSet, resolves a FormCraft configuration for each node type, and delegates rendering to either the flat NestedFormRenderer (for GroupLayout.None) or a layout component.
3. Each FormNode owns an independent FormCraftComponent instance. On valid submit, the typed callback forwards the current model value to the top-level OnValidSubmit callback.

References

• FormCraft: https://phmatray.github.io/FormCraft/home
• MudBlazor: https://mudblazor.com