In this blog post, we will discuss how to work with file uploads in a Ruby on Rails application using Active Storage.
Active Storage provides a simple way to upload files to cloud services like Amazon S3, Google Cloud Storage, etc. ActiveRecord models don't need to be modified with additional columns to associate with files. Active Storage represents files that are attached to ActiveRecord objects via ActiveStorage::Blob and ActiveStorage::Attachment.
ActiveStorage::Blob is a model of the metadata of an uploaded file, like the filename, content-type, and the URL of the actual file in the cloud service. It doesn't contain the binary data of the uploaded file.
ActiveStorage::Attachment is a join model that links the blob to the actual ActiveRecord model like a User, or a Post, etc.
In the database, these two models are represented by the following tables:
active_storage_blobs
active_storage_attachments
By inspecting the table, we can see that active_storage_attachments has a foreign key that references the id of active_storage_blobs.
Active Storage Field Management in ActiveRecord Models
In my Rails application, I have set up my Post ActiveRecord model to include an Active Storage field named photos :
# app/models/post.rb
class Post < ApplicationRecord
belongs_to :user
has_many_attached :photos
end
The has_many_attached :photos indicates that a single Post record can have multiple attached photos, each represented as an instance of ActiveStorage::Attachment.
Handling File Uploads Directly with ActiveRecord model
Given a Post record which already exists in the database, we can easily add or remove photos from it by calling post.photos.attach() and post.photos.purge(). This is quite straight forward, and so I would just skip elaborating about this.
Handling File Uploads with ActiveStorage::Blob
But what if we want to allow file upload before the Post record exists in the database? This is useful in a scenario where we want users to be able to upload files before the creation of a new Post. In the following sections, I would like to share my sample code which handles file uploads both before and after a Post creation.
Firstly, here's the Stimulus.js controller, which handles the photos upload and removal via HTTP request:
// app/javascript/controllers/upload_controller.js
import { Controller } from "@hotwired/stimulus";
export default class extends Controller {
static values = { postId: Number };
static targets = [
"filesInput",
"fileItem",
"filesContainer",
];
uploadFile(event) {
event.preventDefault();
const filesInput = this.filesInputTarget;
let files = Array.from(filesInput.files);
let formData = new FormData();
if (this.hasPostIdValue) {
formData.set("post_id", this.postIdValue);
}
files.forEach((file) => {
formData.append("photos[]", file);
});
fetch("/uploads", {
method: "POST",
body: formData,
headers: {
"X-CSRF-Token": document
.querySelector('meta[name="csrf-token"]')
?.getAttribute("content"),
},
})
.then((response) => {
return response.json();
})
.then((data) => {
if (data.result === "success") {
this.filesContainerTarget.innerHTML += data.html;
filesInput.value = "";
}
});
}
removeFile(event) {
event.preventDefault();
const signedId = button.dataset.signedId;
fetch(`/uploads/${signedId}`, {
method: "DELETE",
headers: {
"X-CSRF-Token": document
.querySelector('meta[name="csrf-token"]')
?.getAttribute("content"),
},
})
.then((response) => {
return response.json();
})
.then((data) => {
if (data.result === "success") {
const targetToRemove = this.fileItemTargets.find(
(t) => t.dataset.signedId === signedId
);
if (targetToRemove) {
targetToRemove.remove();
}
}
})
}
}
In the Rails app, here's the UploadsController which handles the file upload and removal:
# app/controllers/uploads_controller.rb
class UploadsController < ApplicationController
def create
photos = params.require(:photos)
post_id = params[:post_id]
blobs = []
photos.each do |photo|
blob =
ActiveStorage::Blob.create_and_upload!(
io: photo,
filename: photo.original_filename,
content_type: photo.content_type,
)
if post_id.present?
post = Post.find(post_id)
post.photos.attach(blob.signed_id)
end
blobs.push(blob)
end
html_content =
render_to_string(
partial: "posts/photos_list",
locals: {
blobs: blobs,
hidden_input: true
},
)
render json: { result: "success", html: html_content }
end
def destroy
# Fetch the blob using the signed id
blob = ActiveStorage::Blob.find_signed(params[:id])
if blob
if blob.attachments.any?
# the blob is attached to post record
blob.attachments.each { |attachment| attachment.purge }
else
blob.purge
end
render json: { result: "success" }
else
# blob not found
head :unprocessable_entity
end
end
private
end
Here's the PostsController which handle the CRUD of the Post model:
class PostsController < ApplicationController
before_action :authenticate_user!
before_action :set_post, only: %i[ show edit update destroy ]
# GET /posts or /posts.json
def index
@posts = current_user.posts.all
end
# GET /posts/1 or /posts/1.json
def show
end
# GET /posts/new
def new
@post = current_user.posts.new
end
# GET /posts/1/edit
def edit
end
# POST /posts or /posts.json
def create
file_signed_ids = params[:post].delete(:photo_signed_ids)
@post = current_user.posts.new(post_params)
respond_to do |format|
if @post.save
# for photos uploaded, attach the blob's signed_id to post record
attach_files(file_signed_ids)
format.html { redirect_to post_url(@post), notice: "Post was successfully created." }
format.json { render :show, status: :created, location: @post }
else
format.html { render :new, status: :unprocessable_entity }
format.json { render json: @post.errors, status: :unprocessable_entity }
end
end
end
# PATCH/PUT /posts/1 or /posts/1.json
def update
respond_to do |format|
if @post.update(post_params)
format.html { redirect_to post_url(@post), notice: "Post was successfully updated." }
format.json { render :show, status: :ok, location: @post }
else
format.html { render :edit, status: :unprocessable_entity }
format.json { render json: @post.errors, status: :unprocessable_entity }
end
end
end
# DELETE /posts/1 or /posts/1.json
def destroy
@post.destroy
respond_to do |format|
format.html { redirect_to posts_url, notice: "Post was successfully destroyed." }
format.json { head :no_content }
end
end
private
# Use callbacks to share common setup or constraints between actions.
def set_post
@post = current_user.posts.find(params[:id])
end
# Only allow a list of trusted parameters through.
def post_params
# params.fetch(:post, {})
params.require(:post).permit(:message, photos: [])
end
def attach_files(file_signed_ids)
if file_signed_ids.present?
file_signed_ids.each do |signed_id|
@post.photos.attach(signed_id)
end
end
end
end
Here's the erb templates used for the form UI:
# app/views/posts/_form.html.erb
<%= form_with(model: post, class: "contents") do |form| %>
<div class="mt-10">
<%= form.label :message %>
<%= form.text_field :message %>
</div>
<div
class="my-10"
data-controller="upload"
<% if post.persisted? %>
data-upload-post-id-value="<%= post.id %>"
<% end %>
>
<div>
<%= form.label :photos %>
<div data-upload-target="filesContainer">
<%
photos = post.persisted? ? post.photos : []
blobs = photos.map { |photo| photo.blob }
%>
<% if blobs.present? %>
<%= render partial: "posts/photos_list",
locals: {
blobs: blobs,
hidden_input: false
} %>
<% end %>
</div>
</div>
<div class="w-full block">
<%= file_field_tag "photos[]",
multiple: true,
id: "photos",
data: {
upload_target: "filesInput"
} %>
<button
class="btn btn-primary py-1 px-2"
data-action="click->upload#uploadFile"
>
<span class="button-span flex items-center justify-center">
upload
</span>
</button>
</div>
</div>
<div class="inline">
<%= form.submit class: "rounded-lg py-3 px-5 bg-blue-600 text-white inline-block font-medium cursor-pointer" %>
</div>
<% end %>
# app/views/posts/_photos_list.html.erb
<% blobs.each do |blob| %>
<% signed_id = blob.signed_id
display_name = blob.filename.to_s
blob_path = rails_blob_path(blob, disposition: "attachment") %>
<div
id="<%= display_name %>"
class="my-2"
data-signed-id="<%= signed_id %>"
data-upload-target="fileItem"
>
<%= link_to display_name,
blob_path,
title: display_name,
class: "no-underline hover:underline" %>
<% if hidden_input %>
<input
type="hidden"
name="post[photo_signed_ids][]"
value="<%= signed_id %>"
>
<% end %>
<button
id="remove-button"
class="btn btn-primary py-1 px-2 ml-5"
data-action="click->upload#removeFile"
data-signed-id="<%= signed_id %>"
>
<span class="button-span w-5 h-5 flex items-center justify-center">X</span>
</button>
</div>
<% end %>
Handling Photos Upload and Removal before the creation of a new Post
In the new Post creation form, user is able to upload and remove photos. Here's some screenshots of the new Post creation form:
When the form is freshly loaded:
When user has filled in the message and uploaded some photos:
After user clicking the Create Post button, the new Post is created:
Uploading photos before the creation of a new Post
Let's start with handling files upload.
Before creating the Post, user can select multiple photos for upload. When the upload button is clicked, this action is handled by upload_controller.js in uploadFile():
// app/javascript/controllers/upload_controller.js
export default class extends Controller {
...
uploadFile(event) {
...
const filesInput = this.filesInputTarget;
let files = Array.from(filesInput.files);
let formData = new FormData();
...
files.forEach((file) => {
formData.append("photos[]", file);
});
fetch("/uploads", {
method: "POST",
body: formData,
...
})
.then((response) => {
return response.json();
})
.then((data) => {
if (data.result === "success") {
this.filesContainerTarget.innerHTML += data.html;
filesInput.value = "";
}
});
}
It makes a HTTP POST request to the /uploads endpoint, where the selected photos are sent as photos[] param.
In the Rails app, the above HTTP request is handled by create action in the UploadsController:
# app/controllers/uploads_controller.rb
class UploadsController < ApplicationController
def create
photos = params.require(:photos)
...
blobs = []
photos.each do |photo|
blob =
ActiveStorage::Blob.create_and_upload!(
io: photo,
filename: photo.original_filename,
content_type: photo.content_type,
)
...
blobs.push(blob)
end
html_content =
render_to_string(
partial: "posts/photos_list",
locals: {
blobs: blobs,
hidden_input: true
},
)
render json: { result: "success", html: html_content }
end
...
end
It gets an array of photos from the photos param, and uploads each of them via ActiveStorage::Blob.create_and_upload!().
The uploaded blobs are stored in the blobs array, which is passed into the app/views/posts/_photos_list.html.erb partial. For each of the blob, the partial produces a html snippet similar to the below:
<div ... data-signed-id="eyJfcmFpb..." data-upload-target="fileItem">
<a title="cat-2.jpg" ... href="/rails/active_storage/blobs/redirect/eyJfcmFpb.../cat-2.jpg?disposition=attachment">cat-2.jpg</a>
<input type="hidden" name="post[photo_signed_ids][]" value="eyJfcmFpb...">
<button ... data-action="click->upload#removeFile" data-signed-id="eyJfcmFpb...">
<span ...>X</span>
</button>
</div>
These html contents are returned to the caller, which is upload_controller.js. The contents are appended into the filesContainer section of the form. So in the form, we can see that these UI elements are shown for each of the uploaded file:
- The file name with a downloadable link
- A X remove button, which allows user to remove the photo
- The photo's signed id as a hidden input field
Upon clicking the Create Post button, the Post creation is handled here:
class PostsController < ApplicationController
...
def create
file_signed_ids = params[:post].delete(:photo_signed_ids)
@post = current_user.posts.new(post_params)
respond_to do |format|
if @post.save
# for photos uploaded, attach the blob's signed_id to post record
attach_files(file_signed_ids)
format.html { redirect_to post_url(@post), notice: "Post was successfully created." }
...
else
format.html { render :new, status: :unprocessable_entity }
...
end
end
end
private
...
def attach_files(file_signed_ids)
if file_signed_ids.present?
file_signed_ids.each do |signed_id|
@post.photos.attach(signed_id)
end
end
end
end
It gets an array of blob's signed ids from the photo_signed_ids params. These are the hidden input fields which represent the uploaded blobs's signed id.
After creating the new post via @post.save, it calls attach_files(file_signed_ids) to attach each of the signed ids to the Post.
So we have covered how to support photos upload before a Post creation, and then attach the uploaded blobs to the Post after the model creation.
Removing photos before the creation of a new Post
Next let's dwell into the file removal.
In the form, user is able to click on the X button to remove a particular photo they have uploaded. This action is handled by upload_controller.js in removeFile():
// app/javascript/controllers/upload_controller.js
export default class extends Controller {
...
removeFile(event) {
...
const signedId = button.dataset.signedId;
fetch(`/uploads/${signedId}`, {
method: "DELETE",
headers: {
"X-CSRF-Token": document
.querySelector('meta[name="csrf-token"]')
?.getAttribute("content"),
},
})
.then((response) => {
return response.json();
})
.then((data) => {
if (data.result === "success") {
const targetToRemove = this.fileItemTargets.find(
(t) => t.dataset.signedId === signedId
);
if (targetToRemove) {
targetToRemove.remove();
}
}
})
}
}
It makes a HTTP DELETE request to the /uploads endpoint, passing in the blob's signed id.
In the Rails app, the above HTTP request is handled by destroy action in the UploadsController:
# app/controllers/uploads_controller.rb
class UploadsController < ApplicationController
...
def destroy
# Fetch the blob using the signed id
blob = ActiveStorage::Blob.find_signed(params[:id])
if blob
if blob.attachments.any?
# the blob is attached to post record
blob.attachments.each { |attachment| attachment.purge }
else
blob.purge
end
render json: { result: "success" }
else
# blob not found
head :unprocessable_entity
end
end
private
end
In this context, blob.attachments.any? returns false, as the blob is not attached to any Post yet. It then calls blob.purge and remove the blob.
When the success response is received in upload_controller.js, it removes the photo's html element from the form UI:
if (data.result === "success") {
const targetToRemove = this.fileItemTargets.find(
(t) => t.dataset.signedId === signedId
);
if (targetToRemove) {
targetToRemove.remove();
}
}
Handling Photos Upload and Removal for existing Post
For existing Post, in the edit form, user is also able to upload and remove photos. Here's a screenshot of the edit Post form:
Uploading photos for existing Post
To support this scenario, we would need to make some modification to the file upload mechanism described above. In the erb template for the form UI:
# app/views/posts/_form.html.erb
<%= form_with(model: post, class: "contents") do |form| %>
...
<div
...
data-controller="upload"
<% if post.persisted? %>
data-upload-post-id-value="<%= post.id %>"
<% end %>
>
<div>
<%= form.label :photos %>
<div data-upload-target="filesContainer">
<%
photos = post.persisted? ? post.photos : []
blobs = photos.map { |photo| photo.blob }
%>
<% if blobs.present? %>
<%= render partial: "posts/photos_list",
locals: {
blobs: blobs,
hidden_input: false
} %>
<% end %>
</div>
</div>
...
</div>
<div ...>
<%= form.submit ... %>
</div>
<% end %>
For existing Post, post.persisted? returns true. It then adds a data attribute data-upload-post-id-value="<%= post.id %>" to the form, which represents the Post record's id.
The div filesContainer is used to list the existing photos of a Post. In here, it gets the photos list by calling post.photos and turns that into a blobs array by calling blobs = photos.map { |photo| photo.blob }. The blobs array is passed into the posts/photos_list partial to list each of the photo in the form UI.
In the edit Post form, when user adds more photos and click on the upload button, the action is again handled by upload_controller.js in uploadFile():
// app/javascript/controllers/upload_controller.js
export default class extends Controller {
static values = { postId: Number };
...
uploadFile(event) {
...
let formData = new FormData();
if (this.hasPostIdValue) {
formData.set("post_id", this.postIdValue);
}
files.forEach((file) => {
formData.append("photos[]", file);
});
fetch("/uploads", {
...
})
...
}
...
}
Now the Post's id is set in the formData via formData.set("post_id", this.postIdValue).
In Rails, this request is then handled by UploadsController in create:
# app/controllers/uploads_controller.rb
class UploadsController < ApplicationController
def create
...
post_id = params[:post_id]
...
photos.each do |photo|
blob = ActiveStorage::Blob.create_and_upload!(...)
if post_id.present?
post = Post.find(post_id)
post.photos.attach(blob.signed_id)
end
...
end
...
end
...
end
After the photo is uploaded as blob, it checks whether post_id.present?. This returns true now, because for an existing Post, the Post's id is set as a data attribute in the previous erb template. It then find the Post by id and attach the blob to it by calling post.photos.attach(blob.signed_id).
So now the photo blobs are successfully uploaded and attached to the Post.
Removing photos for existing Post
Next we would look into how to handle photos removal for an existing Post.
# app/controllers/uploads_controller.rb
class UploadsController < ApplicationController
...
def destroy
# Fetch the blob using the signed id
blob = ActiveStorage::Blob.find_signed(params[:id])
if blob
if blob.attachments.any?
# the blob is attached to post record
blob.attachments.each { |attachment| attachment.purge }
else
...
end
render json: { result: "success" }
else
# blob not found
head :unprocessable_entity
end
end
...
end
The HTTP delete request is handled by UploadsController in destroy action. Since the blob is now attached to a Post, blob.attachments.any? returns true. It calls blob.attachments.each { |attachment| attachment.purge }, which removes the attachment from the Post, and then the blob itself is purged automatically.
So now the photo is successfully removed from the Post and also deleted from the cloud service.
Conclusion
In conclusion, we have looked into how to handle files upload and removal via ActiveStorage::Blob, and it covers scenarios both before and after a model creation. I hope this walkthrough has been helpful for understanding the ins and outs of file uploads with Active Storage. Happy coding!
