hyva-cms-custom-field_skill

Overview

This skill helps you create custom field types and field handlers for Hyvä CMS components. It explains when to choose a basic input, an inline handler, or a modal-based handler and provides the concrete implementation patterns required for Hyvä Liveview editor integration. It focuses on correct template structure, Alpine.js integration, and registration steps so the field works reliably in the CMS editor.

How this skill works

The skill inspects the desired field behavior (simple input, inline enhancement, or modal selector) and maps that to a clear implementation pattern: templates, Alpine components, and registration points. It enforces Hyvä-specific requirements such as container IDs, input naming, updateWireField vs updateField usage, JSON encoding of complex values, and layout registration for modal handlers. It also identifies required module dependencies and recommends commands to run in the dev environment.

When to use it

• You need a specialized CMS input for Hyvä (date range, color picker, range slider).
• You require an inline enhanced control inside a field (searchable dropdown, swatches).
• You need a modal selector for complex selections (product picker, link builder, media gallery).
• You must store structured data (JSON object/array) from a CMS field.
• You want consistent integration with Hyva_CmsLiveviewEditor and Magewire validation.

Best practices

• Choose pattern based on UI complexity: Basic for simple inputs, Inline for small interactive controls, Modal for complex selection workflows.
• Follow template requirements: container ID field-container-{uid}_{fieldName}, input name {uid}_{fieldName}, and validation container ids.
• Always use null coalescing for defaults (e.g. $block->getData('value') ?? '' or ?? []), never type-cast the stored value.
• JSON-encode complex structures when writing to hidden inputs and handle both array and JSON-string inputs when initializing the handler.
• Use updateWireField for server-synced fields and updateField for preview-only or debounced updates.
• Register modal handlers in before.body.end via layout XML; inline handlers do not need layout registration.

Example use cases

• Add a color_picker field that stores a hex string and displays swatches inline.
• Create a product_selector modal that returns a JSON array of product ids and thumbnails.
• Implement a date_range basic field with custom validation attributes and HTML5 pattern enforcement.
• Build a searchable_select inline handler that uses wire:ignore and an Alpine.js component.
• Create a link_builder modal handler that outputs a JSON object with type, url, and label.