Refactor Gallery: Unified Schema for Multiple Images, Animation, and Optional Links

[Rutjake]

🛠 Refactor Description

The gallery backend is to be refactored to align with the members or newsApi module patterns. All primary assets are to be moved directly to the photo_object collection, and the dependency on the photo_version collection is to be removed to create a flatter, more efficient data structure.

---

🔍 Reason for Refactor

The current implementation relies on a complex relational structure (photo_version collection) which introduces unnecessary overhead and complicates data management. By flattening the schema and moving assets directly to the photo_object collection:

• API performance is improved by reducing the number of database joins.
• Code maintainability is increased by unifying the data fetching pattern with existing members and newsApi modules.
• Scalability is enhanced, allowing for a more flexible way to manage additional media assets (multiple images, animations) and external links per object.

---

🛑 Current Code Issues

The following patterns are to be deprecated and replaced:

• Inefficient Data Fetching: Currently, a secondary query or deep join is required to access the photo_version collection (e.g., preview.* and full.*). This results in overly complex readItems configurations.
  • Example to be removed: fields: ['*', 'preview.*', 'full.translations.*']
• Over-engineered Logic: The frontend currently maps one image into a "version" object. This logic is to be replaced by a direct mapping of asset IDs to URLs.
  • Example to be removed: photo.versions?.preview ? [[photo.versions.preview.image]] : []
• Lack of Content Flexibility: The current structure only supports a single preview and full image. There is no native support for multiple frames, animations, or external project links within the standard photo_object.

---

🛠️ 1. Directus Schema Changes

The photo_object collection is to be modified to include the following fields directly:

• image (Image/File, Required) - Primary preview/static image.
• image_2 (Image/File, Optional)
• image_3 (Image/File, Optional)
• animation (Video/File, Optional)
• link (URL/String, Optional) - External reference 1.
• link_2 (URL/String, Optional) - External reference 2.

---

✅ 2. Technical Implementation Details

API & Data Fetching

• Interface Update: The PhotoObject interface is to be updated to reflect the flat structure. All legacy versions or photo_version types are to be removed.
• API Service: The galleryApi is to be refactored to request fields directly from photo_object. Implementation is to include try-catch blocks and FetchBaseQueryError to match the error-handling pattern found in membersApi and newsApi.

Logic & Hook Integration

• Data Mapping: In the useGetDirectusGalleryImages hook, asset IDs are to be converted into full URLs using the ${directusBaseUrl}/assets/${id} pattern.
• Link Handling: The linkify hook/utility is to be integrated to process link and link_2. This ensures that external URLs are handled safely and consistently.
• Conditional Logic: Strict checks are to be implemented to ensure optional fields are not rendered in the UI if the data is null or undefined.

UI Rendering

• Frames Composition: Assets (image, image_2, image_3, and animation) are to be bundled into the frames property as a single row array.
• Button Components:
  • The Animation button is only to be rendered if an animation URL is present.
  • Link buttons (e.g., "Project" or "More") are only to be rendered if a valid URL is returned after being processed by the linkify logic.

🏁 Acceptance Criteria

• Gallery items support up to 3 images and 1 animation.
• UI does not show empty slots or broken buttons for missing optional data.
• External links are processed via the linkify logic and appear only when data is present.
• The data fetching pattern is unified with the members and newsApi modules.
• Redundant relational fetches for photo_version are removed.

---

📋 Additional Information

When you start working on Directus, please ask the team veterans to create an account for you (if you don’t have one yet).

🔗 Directus Documentation

📷 Preview: