NuGet Package of the Week: A different take on ASP.NET MVC Forms with ChameleonForms

One of the nice things about any modular system (like ASP.NET) is the ability to swap out the parts you don't like. As the authors of ChameleonForms state, HTML forms is a pain. It's repetitive, it's repetitive, and it's boring. While ASP.NET MVC's Form Helpers help a lot, they felt that helper methods like Html.EditorForModel didn't go far enough or give you enough flexibility. ChameleonForms adds its own templating model and attempts to be as DRY as possible. It also takes a number of issues head on like better handling for drop-down lists and lists of radio buttons, and it even supports Twitter Bootstrap 3 to you can bang out HTML forms ASAP.

ChameleonForms also is a nice example of a tidy and well-run small open source project. They've got a public Trello backlog board, excellent documentation, a continuous integration build, a good example project, and of course, they're on NuGet. Check out the other projects that the folks in the "MRCollective" work on as well, as they've got their own GitHub organization.

Often ChameleonForms tries to use C# for the whole form, rather than switching back and forth from Div to Html Helper. For example:

@using (var f = Html.BeginChameleonForm()) {
    using (var s = f.BeginSection("Signup for an account")) {
        @s.FieldFor(m => m.FirstName)
        @s.FieldFor(m => m.LastName)
        @s.FieldFor(m => m.Mobile).Placeholder("04XX XXX XXX")
        @s.FieldFor(m => m.LicenseAgreement).InlineLabel("I agree to the terms and conditions")
    }
    using (var n = f.BeginNavigation()) {
        @n.Submit("Create")
    }
}

This is the whole form using usings for scoping, and it's nice and clean.  How about a comparison example? Here's standard ASP.NET MVC:

@using (Html.BeginForm())
{

And here is the same form with ChameleonForms.

@using (var f = Html.BeginChameleonForm()) {
    using (var s = f.BeginSection("A form")) {
        @s.FieldFor(m => m.RequiredString).Label("Some string")
        @s.FieldFor(m => m.SomeEnum)
        @s.FieldFor(m => m.SomeCheckbox).InlineLabel("Are you sure?")
    }
    using (var n = f.BeginNavigation()) {
        @n.Submit("Submit")
    }
}

But these are basic. How about something more complex? This one has a bunch of variety, a number overloads and customizations, as well as a FileUpload (note that the form is a Multipart form):

@using (var f = Html.BeginChameleonForm(method: FormMethod.Post, enctype: EncType.Multipart))
{
@f.LabelFor(m => m.SomeCheckbox).Label("Are you ready for: ") @f.FieldElementFor(m => m.SomeCheckbox) @f.ValidationMessageFor(m => m.SomeCheckbox)

@f.FieldElementFor(m => m.RequiredStringField).TabIndex(4)

    using (var s = f.BeginSection("My Section!", InstructionalText(), new{@class = "aClass"}.ToHtmlAttributes()))
    {
        using (var ff = s.BeginFieldFor(m => m.RequiredStringField, Field.Configure().Attr("data-some-attr", "value").TabIndex(3)))
        {
            @ff.FieldFor(m => m.NestedField).Attr("data-attr1", "value").TabIndex(2)
            @ff.FieldFor(m => m.SomeEnum).Attr("data-attr1", "value")
            @ff.FieldFor(m => m.SomeEnum).Exclude(SomeEnum.SomeOtherValue)
        }
        @s.FieldFor(m => m.SomeCheckbox).AsDropDown()
        using (var ss = s.BeginSection("Nested section"))
        {
            @ss.FieldFor(m => m.FileUpload).Attr("data-attr1", "value")
        }
        @s.FieldFor(m => m.RequiredStringField).OverrideFieldHtml(new MvcHtmlString("Custom html she-yeah!"))
        @s.FieldFor(m => m.TextAreaField).Cols(60).Rows(5).Label("Some Label").AutoFocus().TabIndex(1)
        @s.FieldFor(m => m.SomeCheckbox).InlineLabel("Some label").WithHint("Format: XXX")
        @s.FieldFor(m => m.SomeCheckbox).AsRadioList().WithTrueAs("True").WithFalseAs("False")
        @s.FieldFor(m => m.ListId)
        @s.FieldFor(m => m.ListId).AsRadioList()
        @s.FieldFor(m => m.SomeEnums)
        @s.FieldFor(m => m.SomeEnumsList).AsRadioList()
        @s.FieldFor(m => m.Decimal)    
        @s.FieldFor(m => m.Int).AsInputGroup().Append(".00").Prepend("$")
        @s.FieldFor(m => m.DecimalWithFormatStringAttribute)
        @s.FieldFor(m => m.NullableInt)
        @s.FieldFor(m => m.Child.ChildField)
        @s.FieldFor(m => m.Child.SomeEnum).AsRadioList()
        @s.FieldFor(m => m.RequiredStringField).Disabled()
        @s.FieldFor(m => m.RequiredStringField).Readonly()
    }
    using (var n = f.BeginNavigation())
    {
        @n.Submit("Submit")
        @n.Reset("Reset")
    }
}

ChameleonForms also has a special NuGet package if you're using TwitterBootstrap that changes how forms with the BeginChameleonForm method render.

ChameleonForms also has some convenient extra abilities, like being able to automatically infer/create a [DisplayName] so you don't have to. If you're doing Forms in English and your preferred Display Name will end up just being your variable name this can be a useful time saver (although you may have opinions about its purity.)

So instead of the tedium of:

[DisplayName("Email address")]
public string EmailAddress { get; set; }

[DisplayName("First name")]
public string FirstName { get; set; }

You can just say this once, picking just one...this is an example where they use HumanizedLabels.

HumanizedLabels.Register(LetterCasing.AllCaps) => "EMAIL ADDRESS"
HumanizedLabels.Register(LetterCasing.LowerCase) => "email address"
HumanizedLabels.Register(LetterCasing.Sentence) => "Email address"
HumanizedLabels.Register(LetterCasing.Title) => "Email Address"

If you've got a lot of Forms to create and they're just no fun anymore, you should definitely give ChameleonForms a try. If you're a Twitter Bootstrap shop, doubly so, as that's where ChameleonForms really shines.

I'll do a few other posts exploring different ways to for Forms in ASP.NET MVC in the coming weeks. Be sure to explore the NuGet Package of the Week Archives as well!

PLUG: Did you know I have a YouTube channel? Subscribe over here. I've got tutorials on how to effectively use Windows 8 and 8.1, Build to Build walkthroughs of the latest versions of Windows 10, and I just started a new series I'm sure you'll want to share with your family called "How to REALLY use Microsoft Office." Help me out and spread the word!