model_driven_api 3.5.6 → 3.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 394acca44589bd5e704f0cbf966eab8eded237d1aafdcbc0f2a14318b78ceadc
-  data.tar.gz: 302dfcc51da16d380148f5fc1953065a0cf537657bb713bc705dab5184a8a4d2
+  metadata.gz: f9f41789e4969e40d7ea928d17463c69b067109d104f4c5c14d2d8885670c08d
+  data.tar.gz: df3716c785822a97d1a17374d64193eb40408735bfc93982f1d12f9ec044a2fe
 SHA512:
-  metadata.gz: 7da1bbd9f1f565296c34479faefba15d9ba77036cea33904740e2c74c646b7aef9c90681e8fdcec8b254efea20818c0719188271f135d58dccac4064100e0c90
-  data.tar.gz: 10702aeed1e9c0c925faa0214c01f0e2ed12187c09a23b559e5f9b1af89ce25cbe268883508bd7c9f75911aba49a2177190177eceb24c6e1947331420f0985dd
+  metadata.gz: 0d6a4d31ecdb991590f78fdafca0b955f833e01abce3796cc69b70626d65201023fe2582b610941aab91834a621849f37fead2241cec4b497a3c758fb3f5b376
+  data.tar.gz: de120a2d0bfbe673d69695a44e2105fe8f16c13b422cefefa6f97ad93a8e40e04fa376e06242fd6b6005b796d0e3e00580fb3b77da2fe7d44d34eeb576a9ac82

data/app/controllers/api/v2/info_controller.rb

@@ -1135,6 +1135,230 @@ Content-Type: application/json
   "count": 156
 }
 
+```
+
+## ActiveStorage Integration: React Frontend & Rails Backend
+
+### Overview
+
+This guide explains how to handle file uploads (via Camera or Gallery) and attachment deletions using a **React** frontend and a **Ruby on Rails** backend.
+
+The Rails model uses a virtual attribute strategy for deletion:
+
+* **Upload:** handled via `has_many_attached :assets`
+* **Deletion:** handled via `attr_accessor :remove_assets`
+
+---
+
+### 1. Handling File Objects (No "Paths" needed)
+
+In a web/mobile context (React Web or PWA), you do not need a file system path. When a user takes a photo or selects a file, the browser creates a native **`File`** object (a type of `Blob`).
+
+You must send this binary object to the backend using **`FormData`**.
+
+#### React Component Example
+
+This component handles:
+
+1. **File Input:** Supports both gallery selection and direct camera capture on mobile.
+2. **FormData:** Constructs the payload correctly for Rails.
+3. **API Call:** Sends the data via `fetch`.
+
+```jsx
+import React, { useState } from 'react';
+
+const ProductForm = () => {
+  const [title, setTitle] = useState('');
+  const [selectedFiles, setSelectedFiles] = useState([]);
+
+  // Handle file selection
+  const handleFileChange = (event) => {
+    // event.target.files is a FileList; convert to Array for convenience
+    const filesArray = Array.from(event.target.files);
+    setSelectedFiles(filesArray);
+  };
+
+  // Handle form submission
+  const handleSubmit = async (event) => {
+    event.preventDefault();
+
+    // 1. Create the FormData object
+    const formData = new FormData();
+
+    // 2. Append text fields
+    formData.append('product[title]', title);
+
+    // 3. Append FILES
+    // It is crucial to use 'product[assets][]' with brackets.
+    // This tells Rails to treat it as an array of attachments.
+    selectedFiles.forEach((file) => {
+      formData.append('product[assets][]', file);
+    });
+
+    try {
+      const response = await fetch('http://localhost:3000/api/products', {
+        method: 'POST',
+        // IMPORTANT NOTE:
+        // When using FormData, do NOT set 'Content-Type': 'application/json'
+        // and do NOT manually set 'multipart/form-data'.
+        // The browser will automatically set the header with the correct 'boundary'.
+        body: formData,
+      });
+
+      if (response.ok) {
+        console.log("Upload successful!");
+        // Reset form or redirect...
+      } else {
+        console.error("Upload error");
+      }
+    } catch (error) {
+      console.error("Network error:", error);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} style={{ padding: '20px' }}>
+      <div>
+        <label>Product Title:</label>
+        <input 
+          type="text" 
+          value={title} 
+          onChange={(e) => setTitle(e.target.value)} 
+        />
+      </div>
+
+      <div style={{ marginTop: '20px' }}>
+        <label>Photos (Camera or Gallery):</label>
+        {/* accept="image/*": Accepts only images.
+           capture="environment": On mobile, opens the rear camera directly.
+           Remove 'capture' if you want the user to choose between Gallery and Camera.
+           multiple: Allows selecting multiple photos.
+        */}
+        <input 
+          type="file" 
+          accept="image/*" 
+          multiple
+          onChange={handleFileChange} 
+        />
+      </div>
+
+      <button type="submit" style={{ marginTop: '20px' }}>
+        Save Product
+      </button>
+    </form>
+  );
+};
+
+export default ProductForm;
+
+```
+
+---
+
+### 2. Key Implementation Details
+
+#### A. The `capture` Attribute
+
+* `<input type="file" capture="environment" />`: Opens the **rear camera** directly on iOS/Android.
+* `<input type="file" capture="user" />`: Opens the **front camera** (selfie mode).
+* **No `capture` attribute** (but with `accept="image/*"`): The device will prompt the user: *"Take Photo or Photo Library?"*. This is often the best UX.
+
+#### B. The `forEach` Loop
+
+You cannot pass an array directly into `FormData` (e.g., `formData.append('key', myArray)` will not work).
+Rails expects multiple values for the same key. You must append each file individually:
+
+```javascript
+// Correct
+files.forEach(file => formData.append('product[assets][]', file));
+
+```
+
+#### C. The Content-Type Header
+
+This is a common pitfall. When using `fetch` or `axios` with a `FormData` body, **do not set the Content-Type header manually**.
+The browser must generate it automatically to include the boundary:
+`Content-Type: multipart/form-data; boundary=----WebKitFormBoundary...`
+
+---
+
+## 3. Handling Deletion (PATCH Request)
+
+To remove specific attachments using the `remove_assets` virtual attribute defined in your Rails model, send the **Attachment IDs** (not the file objects).
+
+```javascript
+const handleUpdate = async () => {
+  const formData = new FormData();
+  
+  // 1. Add new files (if any)
+  newFiles.forEach(file => formData.append('product[assets][]', file));
+
+  // 2. Add IDs to remove 
+  // (e.g., idsToRemove is an array like [12, 45])
+  idsToRemove.forEach(id => formData.append('product[remove_assets][]', id));
+
+  await fetch(`http://localhost:3000/api/products/${productId}`, {
+    method: 'PATCH',
+    body: formData
+  });
+};
+
+```
+
+Here is the addition to the documentation showing the raw HTTP requests.
+
+---
+
+## 4. Bare Metal HTTP Requests
+
+If you were to inspect the network traffic or manually construct the request (e.g., using raw sockets or a tool like Postman/Insomnia), this is exactly what the payload looks like "over the wire."
+
+### A. POST Request (Upload)
+
+Notice how `multipart/form-data` uses a **boundary** string (randomly generated by the client) to separate different fields.
+
+```http
+POST /api/products HTTP/1.1
+Host: localhost:3000
+Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
+
+------WebKitFormBoundary7MA4YWxkTrZu0gW
+Content-Disposition: form-data; name="product[title]"
+
+My New Product
+------WebKitFormBoundary7MA4YWxkTrZu0gW
+Content-Disposition: form-data; name="product[assets][]"; filename="camera_shot.jpg"
+Content-Type: image/jpeg
+
+(Binary image data goes here...)
+------WebKitFormBoundary7MA4YWxkTrZu0gW
+Content-Disposition: form-data; name="product[assets][]"; filename="gallery_photo.png"
+Content-Type: image/png
+
+(Binary image data goes here...)
+------WebKitFormBoundary7MA4YWxkTrZu0gW--
+
+```
+
+### B. PATCH Request (Deletion via IDs)
+
+When sending the `remove_assets` array via `FormData`, the key is repeated for every ID. This is how HTTP handles arrays in form data.
+
+```http
+PATCH /api/products/100 HTTP/1.1
+Host: localhost:3000
+Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryXyZ123
+
+------WebKitFormBoundaryXyZ123
+Content-Disposition: form-data; name="product[remove_assets][]"
+
+12
+------WebKitFormBoundaryXyZ123
+Content-Disposition: form-data; name="product[remove_assets][]"
+
+45
+------WebKitFormBoundaryXyZ123--
+
 ```
     MARKDOWN
     info

data/lib/model_driven_api/version.rb

@@ -1,3 +1,3 @@
 module ModelDrivenApi
-  VERSION = "3.5.6".freeze
+  VERSION = "3.5.8".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: model_driven_api
 version: !ruby/object:Gem::Version
-  version: 3.5.6
+  version: 3.5.8
 platform: ruby
 authors:
 - Gabriele Tassoni