Form Integration

Automatic integration with Rails forms providing seamless direct file upload functionality through DOM event handling.

Capabilities

Start Function

Initializes Active Storage automatic direct upload handling by setting up DOM event listeners for forms containing direct upload file inputs.

/**
 * Initializes Active Storage automatic direct upload handling
 * Sets up DOM event listeners for forms with direct upload file inputs
 * Can be called multiple times safely - will only initialize once
 */
function start(): void;

Usage Examples:

import { start } from "@rails/activestorage";

// Initialize after DOM content loaded
document.addEventListener("DOMContentLoaded", () => {
  start();
});

// Or initialize immediately if DOM is already ready
start();

The start() function automatically handles:

• Form submission interception for forms with direct upload inputs
• Creation and management of upload controllers
• Progress tracking and error handling
• Hidden form field creation with blob signed IDs

Automatic Form Processing

When start() is called, the library automatically:

1. Intercepts form submissions containing file inputs with data-direct-upload-url attribute
2. Creates DirectUploadsController to manage all file uploads in the form
3. Prevents default form submission until uploads complete
4. Shows processing state by adding data-direct-uploads-processing attribute
5. Submits form automatically after successful uploads

Required HTML Structure:

<form action="/posts" method="post" enctype="multipart/form-data">
  <!-- File input must have data-direct-upload-url attribute -->
  <input type="file" 
         name="post[attachments][]" 
         data-direct-upload-url="/rails/active_storage/direct_uploads"
         multiple>
  
  <button type="submit">Create Post</button>
</form>

Event Handling

The automatic integration dispatches custom DOM events throughout the upload process:

Form-level events (dispatched on <form> element):

• direct-uploads:start - When upload process begins
• direct-uploads:end - When all uploads complete successfully

Input-level events (dispatched on <input> element):

• direct-upload:initialize - For each file when upload is created
• direct-upload:start - When individual file upload begins
• direct-upload:before-blob-request - Before blob metadata request
• direct-upload:before-storage-request - Before file storage upload
• direct-upload:progress - During file upload progress
• direct-upload:error - When upload error occurs
• direct-upload:end - When individual file upload completes

Event Listening Examples:

// Listen for upload progress
document.addEventListener("direct-upload:progress", (event) => {
  const { progress, file } = event.detail;
  console.log(`${file.name}: ${Math.round(progress)}%`);
});

// Handle upload errors
document.addEventListener("direct-upload:error", (event) => {
  const { error, file } = event.detail;
  console.error(`Upload failed for ${file.name}:`, error);
  
  // Prevent default alert
  event.preventDefault();
  
  // Show custom error message
  showCustomError(`Failed to upload ${file.name}: ${error}`);
});

// Track form-level completion
document.addEventListener("direct-uploads:end", (event) => {
  console.log("All uploads completed, form will now submit");
});

File Input Requirements

For automatic processing, file inputs must:

1. Have data-direct-upload-url attribute pointing to the Rails direct upload endpoint
2. Be enabled (not have disabled attribute)
3. Contain files (have files selected)
4. Be within a form that gets submitted

Example with Rails helper:

<%= form_with model: @post do |form| %>
  <%= form.file_field :attachments, 
                      multiple: true, 
                      direct_upload: true %>
  <%= form.submit %>
<% end %>

This generates:

<input type="file" 
       name="post[attachments][]" 
       data-direct-upload-url="/rails/active_storage/direct_uploads"
       multiple>

Processing State Management

During uploads, the form enters a processing state:

• data-direct-uploads-processing attribute is added to the form
• File inputs are disabled to prevent changes during upload
• Form submission is prevented until uploads complete
• Submit button state is preserved and restored

CSS Styling:

/* Style forms during processing */
form[data-direct-uploads-processing] {
  opacity: 0.7;
  pointer-events: none;
}

/* Show loading indicator */
form[data-direct-uploads-processing]::after {
  content: "Uploading files...";
  position: absolute;
  /* Additional styling */
}

Error Handling

The automatic integration provides default error handling:

• Displays browser alert for upload errors (unless prevented)
• Re-enables form inputs when errors occur
• Removes processing state to allow retry
• Preserves form data so users don't lose input

Custom Error Handling:

document.addEventListener("direct-upload:error", (event) => {
  // Prevent default alert
  event.preventDefault();
  
  const { error, file } = event.detail;
  
  // Show custom error UI
  showToast(`Upload failed: ${file.name}`, "error");
  
  // Log for debugging
  console.error("Direct upload error:", error);
});