skip to content

In a Rails form, what does f.file_field change about the surrounding form_with, and what does the controller receive for an uploaded CV?

level: juniorimportance: should knowfreq 45%

answer

  1. one helper flips the whole form
  2. builder.multipart = true
  3. enctype written without asking
  4. ActionDispatch::Http::UploadedFile
  5. never refilled after a failed save

basics

~10 s

f.file_field marks the builder as multipart, so form_with adds enctype="multipart/form-data" without being asked. The controller receives an ActionDispatch::Http::UploadedFile under params[:registration][:cv], and the field is never refilled on re-render.

solid answer

~40 s

Calling `f.file_field :cv` sets the builder's `multipart` flag; when the `form_with` block finishes, Rails reads that flag and writes `enctype="multipart/form-data"` on the form tag, so you do not pass `multipart: true` yourself. The input is `<input type="file" name="registration[cv]" id="registration_cv">`; `accept:` takes a string or an array of MIME types and `multiple: true` changes the name to `registration[cv][]`. In the controller, `params[:registration][:cv]` is an `ActionDispatch::Http::UploadedFile` with `original_filename`, `content_type`, `tempfile` and `read`; with `multiple: true` it is an array of them. A file input never gets a `value`, so after a failed validation the re-rendered form is empty and the attendee must choose the file again.

code

erb · 5 lines
erb
<%= form_with model: @registration do |f| %>
  <%= f.label :cv, "CV (PDF)" %>
  <%= f.file_field :cv, accept: "application/pdf" %>
  <%= f.submit %>
<% end %>

go deeper

for a junior

Recall that f.file_field makes form_with switch to multipart on its own and that the controller gets an uploaded-file object, not a string.

for a middle

Explain how the builder's multipart flag reaches the form tag, what UploadedFile exposes, and why the field is empty after a failed save.

for a senior

Treat filename and content type as untrusted, plan for the lost file on re-render, and know when direct uploads or client-side checks reduce the pain.

for a principal

Decide where file validation and storage boundaries sit, weighing form round trips against direct uploads and background processing.

## Why a file field changes the form A form that uploads files must be submitted with the **multipart** encoding; the default URL-encoded body cannot carry file contents. In plain HTML you remember to add the right `enctype` yourself. Rails' form builder removes that step: the field helper and the form helper coordinate. ## How the flag travels 1. Inside `form_with model: @registration do |f|`, the call `f.file_field :cv` sets `multipart = true` on the builder before rendering the input. 2. `form_with` captures the whole block first, then reads `builder.multipart?`. 3. If it is true, `form_with` adds `enctype="multipart/form-data"` to the form tag it writes around the captured fields. Because the block is rendered before the form tag, a file field anywhere in the form, including inside `fields_for` rows, still marks the outer form. You can also pass `multipart: true` to `form_with` explicitly, for a form whose file input is added later by JavaScript. ## The input itself `f.file_field :cv, accept: ["application/pdf", "application/vnd.oasis.opendocument.text"]` writes: ```html <input accept="application/pdf,application/vnd.oasis.opendocument.text" type="file" name="registration[cv]" id="registration_cv"> ``` - **`accept:`** joins an array into the comma-separated attribute. It only filters the file picker; the server must still validate the type. - **`multiple: true`** lets the user pick several files and appends `[]` to the name, so the parameter arrives as an array. - **`disabled:`** and other attributes pass through like any field. ## What the controller receives Rails' parameter parser turns each uploaded part into an **`ActionDispatch::Http::UploadedFile`**: | Method | Returns | |---|---| | `original_filename` | the name on the attendee's machine, such as `cv.pdf` | | `content_type` | the MIME type the browser declared | | `tempfile` | the `Tempfile` holding the bytes on the server | | `read`, `path`, `size` | delegated to that tempfile | The declared content type and the file name come from the client, so treat both as untrusted. Typically the controller passes the object straight to a model attribute that stores it; how that storage works is a separate subject. ## Re-rendering after a failed save Text fields refill from the record, but a **file input never receives a `value`**: browsers do not allow pages to preselect files, and Rails' file field skips the value attribute. If the registration fails validation because, say, the email is missing, the re-rendered form shows an empty CV field and the attendee has to pick the file again. Common mitigations: - validate the other fields client-side first so the round trip is rarer; - upload the file directly to storage before submit and keep a reference in a hidden field; - show a note near the field saying the file must be chosen again. ## Several files at once With `f.file_field :supporting_documents, multiple: true`, the name ends in `[]` and the parameter arrives as an array of `ActionDispatch::Http::UploadedFile` objects, one per chosen file. The array can also contain an empty string written by a hidden companion input that lets an empty selection still submit the key, so code that loops over the uploads should skip blank entries. Each object is independent: check type and size per file rather than once for the request. ## Common mistakes - Adding `multipart: true` everywhere "just in case" is harmless but unnecessary once a file field is present. - Expecting `accept:` to block other file types on the server. - Writing `<input type="file">` by hand inside `form_with`, which does not set the builder's flag, so the form posts without the multipart encoding and the controller receives only a file name string.

  • Why might a hand-written <input type="file"> inside form_with upload nothing?
    Only the builder's `file_field` sets the `multipart` flag that makes `form_with` write the multipart `enctype`. A hand-written input leaves the form URL-encoded, so the browser sends just the file name as text. Use `f.file_field`, or pass `multipart: true` to `form_with`.
  • Is accept: "application/pdf" enough to guarantee a PDF reaches the server?
    No. `accept:` only filters the browser's file picker, and the user can switch it off or send a request by other means. The `content_type` on the uploaded file is also the client's claim. Validate type and size on the server.

  • You must always pass multipart: true to form_with when the form has a file field.
  • accept: "application/pdf" makes Rails reject other file types on the server.
  • params[:registration][:cv] is a String holding the file's contents.
  • After a failed save the file field keeps the chosen file, like other fields keep their values.
  • content_type on the upload is detected by Rails from the file's bytes.