Form Helpers in Wheels 4.0: Object Forms, HTML5 Fields, and Error Rendering

[bpamiri]

You've hand-written a Wheels form at least once — a dozen <input name="user[email]"> tags, each with a hand-typed value, a hand-typed id so the <label for="..."> lines up, and a loop at the top to print validation errors. It works, until you fat-finger one bracket and that field silently never saves, or validation fails and the value the user typed is gone because you forgot to re-populate one input.

This post is the working tour of the helpers that exist precisely so you stop hand-typing — and stop subtly mis-typing — the name, id, value, maxlength, label, and error wrapper.

Read: https://blog.wheels.dev/posts/form-helpers-objects-and-html5

The one mental model

When you call textField(objectName="user", property="email"), objectName is the variable name — a string — not the object instance. The helper resolves variables["user"] for you, reads .email, and (with the default labelPlacement="around") wraps the input in its label:

<label for="user-email">Email<input type="email" name="user[email]" id="user-email" data-auto-id="user_email" value="dev@example.com" maxlength="255"></label>

The name="user[email]" is the load-bearing part: on submit it round-trips into params.user.email. Bind every field to objectName="user" and the whole form arrives as one params.user struct — which is exactly why controllers do model("User").new(params.user). Pass the object instance instead of its name and you get Wheels.InvalidArgument.

What the post covers

• A complete create/edit form — fields bound to a user object, the cfparam that keeps a failed-save re-render from blowing up, and the controller half that mass-assigns params.user.
• The finite HTML5 roster — emailField, urlField, numberField, telField, dateField, colorField, rangeField, searchField, plus textField with an overridable type. There is no timeField, dateTimeField/datetimeLocalField, monthField, or weekField — reach for one and you get a runtime error. Date/time-as-dropdowns are dateSelect/timeSelect/dateTimeSelect.
• The method override — startFormTag(method="put") rewrites to POST plus a hidden _method field, because HTML forms can't do real PUT/PATCH/DELETE. It also auto-appends the CSRF authenticityTokenField for non-GET methods. Hand-write method="put" on a raw <form> and the browser falls back to GET, leaking the token into the URL.
• The unchecked-checkbox problem — unchecked boxes post nothing in HTML. checkBox defaults to checkedValue=1/uncheckedValue=0, emitting a companion hidden input named user[active]($checkbox); the dispatcher collapses it into the real param only when the box didn't post. Pass uncheckedValue="" and the param goes absent again.
• Object vs Tag helpers — object helpers (textField, select) emit name="user[field]" → nested params.user.field. The *Tag variants (searchFieldTag, selectTag) emit a flat name → params.q. Use object helpers when a model exists; Tag helpers for search bars, filters, and login forms.
• Two error helpers — errorMessagesFor returns a <ul class="error-messages"> of every error on the object; errorMessageOn returns the first message for a single property, inline. Both return "" when clean and both throw Wheels.IncorrectArguments in development if the named variable isn't an object. The field helpers also auto-wrap themselves in your errorElement/errorClass when the bound property is invalid.
• No standalone label() — labels come from the label=/labelPlacement= args on field helpers, which wire for= to the auto-derived id. label="false" suppresses it.

A couple of sharp edges worth flagging here

• All-named args, always. textField("user", "email", label="X") mixes positional and named and will misbehave. The moment you pass options, everything is named.
• errorMessagesFor shows duplicates by default (showDuplicates=true) — pass showDuplicates=false to collapse identical messages.
• Blank checkedValue auto-checks only on numeric 1 or boolean true — a string "true"/"yes" won't. Set checkedValue explicitly to match what your column stores.
• A single select uses exact match, so a stored "Doe,John" won't accidentally select a "Doe" option. Only multiple=true treats the value as a comma list.
• Value precedence — a field reads the bound property only when no value arg was passed (or it's empty). Pass value="..." and it overrides the stored value.

Discussion

What's your house style — one consolidated errorMessagesFor block at the top, or inline errorMessageOn next to each field? Anyone leaning on the *Tag helpers for complex filter bars, or do you wrap those in a throwaway object to get the nested params? And has the missing timeField/dateTimeField ever bitten you mid-build? Replies welcome.