Hero Widget Selector Plugin

A Strapi v5 plugin that provides a custom field for selecting widgets from a filtered collection.

Features

• Custom field type: widget-selector
• Filters widgets by size (S, M, L, XL)
• Default filter set to "S" size
• Admin API endpoint for fetching filtered widgets
• Configurable size filter in field options
• Smart Layout Detection: Automatically detects fallback vs default layouts
• Fallback Layout Support: Shows only widget selector for fallback layouts
• Conditional Layout Support: Shows widget, condition, and layout selectors for default layouts

Installation

Option 1: NPM Package (Recommended for Production)

Note: This is a private package. You need proper authentication to install it.

NPM Authentication Setup

1. Login to NPM (if you have access to @inspirer-dev organization):

   npm login --scope=@inspirer-dev

2. Or create/update .npmrc file in your project root:

   # .npmrc
   @inspirer-dev:registry=https://registry.npmjs.org/
   //registry.npmjs.org/:_authToken=${NPM_TOKEN}

3. For CI/CD environments, set the NPM_TOKEN environment variable:

   export NPM_TOKEN=your_npm_auth_token

Install the Package

# Install from npm
npm install @inspirer-dev/hero-widget-selector

# Or with yarn
yarn add @inspirer-dev/hero-widget-selector

Option 2: Local Development

For local development, you can use the plugin directly from the source:

1. Clone the plugin into your Strapi project's src/plugins/ directory
2. Install dependencies:

   cd src/plugins/hero-widget-selector
   yarn install

3. Build the plugin:

   yarn build

Usage

1. Install the plugin using one of the methods above
2. In your content type builder, add a new field
3. Select "Custom" field type
4. Choose "Widget Selector" from the list
5. Configure the widget size filter in the field options (defaults to "S")
6. The field will display a dropdown with widgets filtered by the selected size

Layout Type Detection

The plugin automatically detects the layout type based on the field name:

Fallback Layouts

• Field names containing: fallbackLayout or fallbackLayouts
• UI shown: Only the widget selector
• Purpose: Simple widget selection without conditions
• Data source: hero-section.fallbackLayout field

Default Layouts

• Field names containing: defaultLayouts (or any other name)
• UI shown: Widget selector + Condition selector + Conditional layout selector
• Purpose: Advanced widget selection with conditional layout support
• Data source: hero-section.defaultLayouts field

Example Schema Usage

{
  "attributes": {
    "defaultLayouts": {
      "type": "dynamiczone",
      "components": ["hero-layouts.xl-l-l", "hero-layouts.xl-s-s-s-s"]
    },
    "fallbackLayout": {
      "type": "dynamiczone",
      "components": ["hero-layouts.xl-l-l", "hero-layouts.xl-s-s-s-s"]
    }
  }
}

API Endpoints

• GET /api/hero-widget-selector/widgets/admin?size=S - Fetch widgets filtered by size
• GET /api/hero-widget-selector/hero-layouts/admin - Fetch default hero layouts
• GET /api/hero-widget-selector/hero-layouts/admin?fallbackOnly=true - Fetch fallback hero layouts only
• GET /api/hero-widget-selector/hero-layouts/admin?search=term - Search layouts by name
• GET /api/hero-widget-selector/hero-layouts/admin?omitLayoutId=123 - Exclude specific layout by ID

Field Configuration

The custom field accepts the following options:

• size: Filter widgets by size (S, M, L, XL) - defaults to "S"

Development

Local Development Workflow

1. For Local Development: Use the plugin directly in src/plugins/hero-widget-selector
2. For Production: Use the npm package @inspirer-dev/hero-widget-selector

Building the Plugin

# Build the plugin
npm run build

# Watch for changes during development
npm run watch

# Verify the plugin structure
npm run verify

Publishing Updates

# Increment version
npm version patch  # or minor/major

# Build and publish
npm run build
npm publish

Linking for Development

If you want to test the npm package locally:

# In the plugin directory
npm link

# In your Strapi project
npm link @inspirer-dev/hero-widget-selector

Docker Development

The plugin works seamlessly with Docker:

• Local Development: Plugin builds from source in src/plugins/
• Production: Plugin is installed as npm dependency, no build step needed

Configuration

Add the plugin to your Strapi config if needed:

// config/plugins.js
module.exports = {
  'hero-widget-selector': {
    enabled: true,
  },
};