Migrate module to exploit all Frontify capabilities

Frontify Module - Major Refactoring and Modernization Plan

Issue Type: Task / Architecture

Priority: Normal

Component: Frontify

Overview

This issue outlines a comprehensive refactoring plan for the Frontify module to modernize its architecture, improve maintainability, and align with Drupal 10+ best practices. The goal is to create a more flexible, extensible, and maintainable codebase while reducing technical debt.

Current State

The current Frontify module has several architectural limitations:

• FieldType: Currently only handles images, with limited support for other media types (Document, Video, Audio)
• FieldFormatter: Multiple formatters exist, each tied to specific media types
• Cardinality: Limited support for multiple values per field
• Frontify Finder: The module includes a ported version of the Frontify Finder JavaScript code, which creates maintenance overhead and version drift

Planned Changes

1. Migrate FieldType to Handle All Media Types

Goal: Create a unified FrontifyAssetField that can handle Document, Video, Audio, and Image assets.

Changes:

• Add media_type field setting to allow configuration of allowed media types per field instance
• Add allowed_extension field setting with AJAX-driven prefilling based on selected media types
• Update schema to include new columns for media type and allowed extensions
• Provide update hooks for existing installations to migrate data

Technical Details:

Schema additions:
- media_type: varchar(50) - stores selected media type(s)
- allowed_extension: text - stores JSON-encoded allowed file extensions

Field settings:
- media_type: checkboxes (file, video, image, document, audio)
- allowed_extension: textarea (prefilled via AJAX based on media_type selection)

2. Migrate FieldFormatter to Single Unified Formatter

Goal: Replace multiple media-type-specific formatters with a single FrontifyAssetFormatter that adapts its output based on the field definition.

Changes:

• Remove FrontifyImageFormatter, FrontifyVideoFormatter, FrontifyDocumentFormatter
• Create unified FrontifyAssetFormatter that reads media_type from field definition
• Formatter automatically renders appropriate output (image thumbnail, video embed, document link, audio player)
• Add formatter settings for display options (thumbnail size, link behavior, etc.)

Benefits:

• Reduced code duplication
• Easier maintenance and testing
• Consistent user experience across media types

3. Handle Multiple Cardinality

Goal: Ensure the widget and formatter properly support fields with unlimited cardinality.

Changes:

• Update FrontifyAssetFieldWidget to properly handle multiple field items
• Ensure AJAX callbacks work correctly for each delta in multi-value fields
• Update formatter to render multiple assets in a grid/list layout
• Add CSS classes for proper styling of multiple assets

Technical Details:

Widget changes:
- Proper delta handling in formElement()
- Unique wrapper IDs per field item
- Correct AJAX wrapper targeting for each delta

Formatter changes:
- Loop through all items in fieldItemList
- Render each item with appropriate media type output
- Support for grid/list display modes

4. Use Frontify Finder as Third-Party Library

Goal: Remove the ported Frontify Finder JavaScript code and use the official library via CDN or npm.

Changes:

• Remove js/frontify_finder.js (the ported Frontify Finder code)
• Add library definition to load Frontify Finder from official Frontify finder library
• Update JavaScript integration to use the official API and exploit extension filters / multiple selection
• Add version pinning to ensure compatibility

Benefits:

• Automatic access to Frontify Finder updates and bug fixes
• Reduced module size
• No version drift between module and official Finder
• Smaller codebase to maintain

Migration Path

For Existing Installations:

1. Update Hooks: Provide update hooks to migrate existing field configurations
   • frontify_update_10003() - Add new schema columns
   • frontify_update_10004() - Migrate formatter configurations
2. Backwards Compatibility: Maintain backwards compatibility during transition period
   • Old formatters remain available but marked as deprecated
   • Automatic migration to new formatter on field save
3. Documentation: Provide clear migration guide for site builders

Labels

architecture refactoring needs-work frontify