Skip to content

🎴 Advanced Cards Plugin

🎯 Overview

The Advanced Cards Plugin (picnic/plugin-advanced-cards) is a professional data block for NocoBase that implements elegant card components using Ant Design V5, with customizable actions and modern UI patterns. It provides rich visual content display capabilities across the platform for galleries, portfolios, and content management interfaces.

🔗 Backend Integration

System-Wide Content Display

  • Template Marketplace: Template browsing and selection
  • Service Marketplace: Creative professional profiles
  • Asset Manager: Media gallery and file browsing
  • Portfolio Management: Project and work showcases
  • Content Libraries: Organized content collections

💡 Benefits to Backend Modules

For Content Management

  • Rich Visual Display: Cover images with elegant empty states
  • Organized Layout: Professional grid arrangement
  • Action Integration: Edit, view, delete directly on cards
  • Responsive Design: Automatic layout adaptation

For Marketplaces

  • Professional Appearance: Native Ant Design V5 styling
  • Quick Actions: Tooltips and hover effects
  • Customizable Branding: Icon and color personalization
  • Empty State Handling: Elegant placeholders when no images

✨ Key Features

🎨 Visual Design

  • Ant Design V5 Cards: Native professional components
  • Cover Images: Auto-detection of attachment fields
  • Elegant Empty States: Professional placeholder when no image
  • Auto-generated Avatars: From title text
  • Theme Integration: Perfect light/dark mode compatibility

🔧 Dual ActionBar System

  • Standard NocoBase ActionBar: Full functionality (top)
  • Native Ant Design ActionBar: Elegant icons (bottom)
  • Configurable Actions: Edit, View, Delete, Custom
  • Tooltips: Informative hover text
  • Visual Feedback: Native hover effects

⚙️ Advanced Configuration

  • Horizontal Layout Modal: Space pattern for clean UI
  • IconPicker: Custom icons per action
  • Conditional Colors:
  • Toggle custom color per action
  • ColorPicker auto-enables/disables
  • Theme colors vs custom colors
  • Schema Persistence: All settings saved in database

🛠️ Technical Architecture

🏗️ Component Structure

Advanced Cards Plugin
├── AdvancedCard.Item (Main Component)
│   ├── Ant Design Card
│   ├── Cover Image Area
│   ├── Avatar Generation
│   ├── Card Content
│   └── ActionBar (Native)
├── AdvancedCard.Designer (Configurator)
│   ├── Field Selection
│   ├── Action Configuration Modal
│   └── IconPicker & ColorPicker
├── createAdvancedCardBlockUISchema
│   └── Block Schema Generator
└── useGridCardActionBarProps (Hook)
    └── ActionBar Logic

🔧 Technologies Used

  • React 18+: Component framework
  • Ant Design v5: Card, Space, ColorPicker, Empty
  • NocoBase Framework: Data blocks, schema system
  • Formily: Form management with x-reactions
  • CSS-in-JS: @emotion for styling
  • TypeScript: Type safety

📊 Configuration Schema

{
  customActionConfig: {
    [actionKey]: {
      icon: string,           // Icon name (e.g., 'EditOutlined')
      color: string,          // Hex color (e.g., '#1890ff')
      customColor: boolean    // Use custom color toggle
    }
  },
  titleField: string,         // Field for card title
  descriptionField: string,   // Field for description
  coverField: string,         // Attachment field for cover
  avatarField: string         // Field for avatar text
}

📦 Installation & Setup

1️⃣ Installation

# Copy to NocoBase plugins directory
cp -r packages/plugins/@picnic/plugin-advanced-cards \
  /path/to/nocobase/packages/plugins/@picnic/

# Enable in admin interface
# Settings → Plugin Manager → Advanced Cards → Enable

2️⃣ Adding Block

  1. Page Edit Mode → Add Block
  2. Data blocks → Advanced Cards
  3. Select collection
  4. Configure fields:
  5. Title field
  6. Description field
  7. Cover image (auto-detects attachments)
  8. Avatar source

3️⃣ Customizing Actions

  1. Use standard ActionBar to configure actions
  2. Click "🎨 Customize Actions" button
  3. Configure per-action:
  4. Select icon from IconPicker
  5. Toggle custom color switch
  6. Choose color with ColorPicker
  7. Settings auto-save to schema

🎯 Use Cases

📦 Template Marketplace

Scenario: Browsing motion graphics templates - Cover: Template preview image - Title: Template name - Description: Template description - Actions: Preview, Purchase, Add to Cart - Benefit: Professional visual browsing

👤 Service Marketplace

Scenario: Creative professional profiles - Cover: Portfolio sample - Avatar: Profile photo - Title: Professional name - Actions: View Profile, Contact, Hire - Benefit: Engaging talent discovery

Scenario: Media library browsing - Cover: Asset thumbnail - Title: File name - Metadata: File type, size - Actions: Download, Edit, Delete - Benefit: Visual asset management

📁 Project Portfolio

Scenario: Client work showcase - Cover: Project hero image - Title: Project name - Description: Brief summary - Actions: View Details, Share - Benefit: Professional presentation

🚀 Advanced Features

🎨 Empty State Excellence

When no cover image is available: - Uses EyeInvisibleTwoTone icon - Displays "No image" text - Maintains consistent card height - Professional placeholder appearance

🔧 Design Patterns

Space Pattern

Horizontal layouts in modals use Ant Design Space: 

<Space direction="horizontal" size="middle">
  <IconPicker />
  <Switch />
  <ColorPicker disabled={!customColor} />
</Space>

X-Reactions

Field dependencies managed automatically: 

{
  'x-reactions': {
    dependencies: ['customColor'],
    fulfill: {
      state: {
        disabled: '{{!$deps[0]}}'
      }
    }
  }
}

🎯 Theme Integration

Uses CSS variables for perfect theme compatibility: 

const { token } = theme.useToken();
// Automatically adapts to light/dark themes

📚 Documentation References

Backend Module Documentation

  • Template Marketplace (TODO)
  • Service Marketplace (TODO)
  • Asset Manager (TODO)

Legacy Documentation

  • Source: OLD_Docs/Front_End_Plugins/Advanced_Cards/
  • Dev Notes: OLD_Docs/Front_End_Plugins/Advanced_Cards/dev_notes.md

🔗 Cross-References

This Plugin Supports

  • Content display across all modules with visual galleries
  • Marketplaces, portfolios, media libraries

📊 Quality Attributes

✨ UX Excellence

  • Professional Design: Native Ant Design components
  • Visual Feedback: Clear interactions and states
  • Accessibility: Proper ARIA labels
  • Responsive: Auto-adapts to screen sizes

🎯 Developer Benefits

  • Pattern Reference: Example of best practices
  • Well-documented: Comprehensive inline comments
  • Extensible: Easy to customize and extend
  • Type-safe: Full TypeScript support

🎓 Lessons Learned

🏆 Critical Patterns Discovered

  1. Space Pattern: Correct solution for horizontal layouts in FormDialog
  2. x-reactions: Automatic field dependency management
  3. CSS Variables: Essential for theme integration
  4. Empty States: Significantly improve UX with minimal effort

⚠️ Common Mistakes Avoided

  • ❌ Using Grid in FormDialog (doesn't work)
  • ❌ Importing Switch from nocobase/client (comes from antd)
  • ❌ Creating ActionBar dynamically (must be in initial schema)
  • ❌ Global variables for data transfer (use schema instead)

🎯 Advantages Over Standard Blocks

📊 vs GridCard Standard

  • ✅ Elegant empty states
  • ✅ Conditional color configuration
  • ✅ Modern Ant Design V5 UI
  • ✅ ActionBar at bottom (cleaner)

📋 vs List/Table Blocks

  • ✅ Richer visual display with images
  • ✅ Gallery-style attractive layout
  • ✅ Better for multimedia content
  • ✅ More modern, intuitive UX