Skip to content

michtio/craftcms-claude-skills / skills/craft-plugins

craft-plugins

Verified

Index and router for plugin-specific Craft CMS 5 guidance — configuration, Twig API, PHP API, migrations, deployment, and pitfalls for the plugins this pack documents. Load whenever a task names a plugin this pack documents, and for passwordless or magic-link auth with no plugin named; read references/<plugin>.md first.

references/embedded-assets.md

View on GitHub
# Embedded Assets

oEmbed plugin by Spicy Web. Lets editors paste URLs (YouTube, Vimeo, Instagram, etc.) into Craft's asset manager and treat them as first-class assets stored as JSON files. Pulls images, embed codes, and metadata automatically. Supports GraphQL. Used in 4/6 projects.

`spicyweb/craft-embedded-assets` — Free (MIT)

## Documentation

- GitHub: https://github.com/spicywebau/craft-embedded-assets
- Templating: https://github.com/spicywebau/craft-embedded-assets/blob/main/docs/templating.md
- GraphQL: https://github.com/spicywebau/craft-embedded-assets/blob/main/docs/graphql.md
- Configuration: https://github.com/spicywebau/craft-embedded-assets/blob/main/docs/configuration.md

When unsure, `WebFetch` the relevant docs page.

## Common Pitfalls

- Forgetting that embedded assets are JSON files — they have `.json` extension and `kind === 'json'`. Asset fields must allow JSON file types, or have no file type restriction.
- Using `asset.url` directly — for an embedded asset, `asset.url` returns the JSON file path, not the embed URL. Always use `craft.embeddedAssets.get(asset)` to get the model.
- Not null-checking — `craft.embeddedAssets.get()` returns `null` if the asset isn't an embedded asset. Always guard with `{% if embed %}`.
- Instagram/social media breakage — social platforms frequently change their oEmbed APIs. Keep the plugin updated.
- Missing whitelist entries — the plugin whitelists allowed domains. If an embed URL doesn't work, check if the domain is in the whitelist config.
- Using deprecated properties — v4+ deprecated `$images` (use `$image`), `$providerIcons` (use `$providerIcon`), `$tags` (use `$keywords`).

## Twig API

### Getting an Embedded Asset

```twig
{% set asset = entry.videoField.one() %}
{% set embed = craft.embeddedAssets.get(asset) %}

{% if embed %}
    <h3>{{ embed.title }}</h3>
    <p>{{ embed.providerName }}</p>

    {# Safe HTML embed code (sanitized) #}
    {{ embed.html }}
{% endif %}
```

### Model Properties

| Property | Type | Description |
|----------|------|-------------|
| `title` | `string` | Embed title |
| `description` | `string` | Embed description |
| `url` | `string` | Original URL |
| `type` | `string` | `video`, `photo`, `rich`, `link` |
| `image` | `string` | Primary image URL |
| `html` | `TwigMarkup` | Sanitized, safe-to-output embed HTML (via `getHtml()`) — output directly, no `\|raw` needed |
| `code` | `string` | Raw, unsanitized embed HTML (only safe to output when `getIsSafe()` is true) |
| `providerName` | `string` | Provider name (YouTube, Vimeo, etc.) |
| `providerUrl` | `string` | Provider URL |
| `providerIcon` | `string` | Provider favicon URL |
| `authorName` | `string` | Content author |
| `authorUrl` | `string` | Author URL |
| `width` | `int` | Embed width |
| `height` | `int` | Embed height |
| `keywords` | `array` | Keywords/tags |

### Model Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `getIsSafe()` | `bool` | Whether embed code URLs are from whitelisted domains |
| `getIframeSrc(params?)` | `string\|null` | Iframe src URL with optional extra params |
| `getIframeCode(params?, attributes?, removeAttributes?)` | `string\|null` | Full iframe HTML with modifications |
| `getVideoId()` | `string\|null` | Video ID for supported providers |
| `getVideoUrl(params?)` | `string\|null` | Video URL with optional params |

### Iframe Customization

```twig
{% set embed = craft.embeddedAssets.get(asset) %}

{# Get iframe src with extra params #}
{{ embed.getIframeSrc(['autoplay=1', 'controls=0']) }}

{# Get full iframe code with params, added attributes, and removed attributes #}
{{ embed.getIframeCode(
    ['autoplay=1', 'playsinline=1'],
    ['loading=lazy'],
    ['frameborder']
)|raw }}
```

### Alternative: From Raw Data

```twig
{# Build from property name/value pairs instead of an asset #}
{% set embed = craft.embeddedAssets.fromData({
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    title: 'Video Title',
    type: 'video',
}) %}
```

## GraphQL

```graphql
{
  entries(section: "videos") {
    ... on videos_default_Entry {
      videoField {
        embeddedAsset {
          title
          url
          type
          providerName
          image
          isSafe
          iframeSrc(params: ["autoplay=1"])
        }
      }
    }
  }
}
```

Returns `null` for assets that aren't embedded.

## Configuration

Settings are configurable via the CP (Settings → Embedded Assets) or config file:

```php
// config/embedded-assets.php
return [
    // Whitelisted domains (URLs must match one of these)
    'whitelist' => [
        'youtube.com',
        'vimeo.com',
        'soundcloud.com',
        // ... add custom domains
    ],

    // Show thumbnails in CP asset indexes
    'showThumbnailsInCp' => true,

    // Min/max dimensions for embedded image thumbnails
    'minImageSize' => 16,
    'maxImageSize' => 2000,
];
```

## Pair With

- **CKEditor** — embed media in rich text fields, use Embedded Assets for standalone media assets
- **ImageOptimize** — regular images use ImageOptimize transforms, embedded assets use their own thumbnails
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall