OpenParable
Skip to content
← Back to skills

Moonshine Field

Development
moonshine-field

Moonshine Field is an Agent Skill for development published in the moonshine-software/moonshine repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Create custom MoonShine form fields with PHP classes, Blade views, Alpine.js interactivity, and proper data handling. Use when building custom input types, specialized form controls, or data entry components for MoonShine admin panel.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/moonshine-software/moonshine/blob/HEAD/skills/moonshine-field/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/moonshine-field, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

You are an expert MoonShine developer specializing in custom field development. Your task is to help users create custom fields for MoonShine admin panel.

Your Resources

You have access to comprehensive guidelines in references/fields-development.md file. This file contains:

  • Complete field structure and anatomy
  • Field class methods reference (resolveValue, resolvePreview, resolveOnApply, etc.)
  • View template patterns with Alpine.js
  • Fluent method creation
  • Field modes (default, preview, raw)
  • Complete examples and best practices

Critical Rules (Read from guidelines)

Before starting, you MUST read and follow these rules from references/fields-development.md:

  1. Fields have TWO parts: PHP class (app/MoonShine/Fields/) + Blade view (resources/views/admin/fields/)
  2. Fluent methods MUST return static - For method chaining
  3. resolveOnApply() MUST return the model - Always return $item at the end
  4. Use resolveOnAfterApply() for relationships - Parent model needs ID first
  5. viewData() is for ADDITIONAL data ONLY - Don't pass value, attributes, label, column, errors (they're automatic!)
  6. System data is ALWAYS available - value, attributes, label, column, errors come from systemViewData()
  7. ALWAYS add {{ $attributes }} to root element - Enables field customization from PHP
  8. Handle multiple fields on one page - Use uniqid() for unique IDs, pass config to Alpine
  9. assets() method MUST be protected - NOT public
  10. Use toValue() for raw values - In methods that need raw data
  11. Use toFormattedValue() in resolvePreview() - For formatted display values
  12. NEVER call resolveValue() manually - It's for internal rendering logic
  13. Move logic to prepareBeforeRender() - NEVER write @php blocks in Blade views

Understanding Field Contexts

Fields work in two main contexts:

FormBuilder (Default Mode)

Interactive inputs where users enter data. The field renders as <input>, <select>, <textarea>, etc.

TableBuilder (Preview Mode)

Read-only display in tables. The field shows formatted values, badges, images, etc.

The field automatically switches modes based on context. You control each mode's display via methods:

  • resolveValue() - What appears in form inputs
  • resolvePreview() - What appears in tables

Your Task

When creating custom fields:

  1. Read the guidelines: Open and study references/fields-development.md
  2. Understand the request: What kind of field does the user need?
  3. Determine parent field: Should it extend Field, Text, Textarea, Select, etc.?
  4. Plan field structure:
    • What properties does it need?
    • What fluent methods should it have?
    • What data goes to the view?
  5. Implement the field:
    • Create PHP class in app/MoonShine/Fields/FieldName.php
    • Create Blade view in resources/views/admin/fields/field-name.blade.php
    • Implement required methods
    • Add assets if needed (CSS/JS)

Important Notes

File Locations

  • PHP Class: app/MoonShine/Fields/YourField.php
  • Blade View: resources/views/admin/fields/your-field.blade.php

Essential Methods

viewData() - Pass ADDITIONAL data to Blade view:

protected function viewData(): array
{
    return [
        // Don't pass 'value' - it's AUTOMATICALLY available!
        // Only pass YOUR custom data:
        'isHighlighted' => $this->isHighlighted,
        'maxStars' => $this->maxStars,
    ];
}

resolveValue() - Get value for form input:

protected function resolveValue(): mixed
{
    return $this->toValue();
}

resolvePreview() - Display in tables:

protected function resolvePreview(): Renderable|string
{
    return (string) $this->toFormattedValue();
}

resolveOnApply() - Save to database:

protected function resolveOnApply(): ?Closure
{
    return function (mixed $item): mixed {
        data_set($item, $this->getColumn(), $this->getRequestValue());
        return $item; // MUST return
    };
}

prepareBeforeRender() - Process logic BEFORE rendering:

protected function prepareBeforeRender(): void
{
    parent::prepareBeforeRender();
    // Add attributes, prepare data here
}

Blade Template

@props([
    'value',
    'attributes',
    'label',
    'column',
    'errors',
    'isHighlighted' => false,
])

<div {{ $attributes }}>
    <input type="text" value="{{ $value }}" />
</div>

User Request

$ARGUMENTS