Blueprint Changes

[jasonvarga]

The Issue

As blueprints are the "things" that define the schema of content (e.g. entries, taxonomies) and other data (e.g. forms), it makes sense for them to be defined on the content container level.

However, Blueprints live in their own separate section of the Control Panel right now. If you go to the Blueprints area, there's no UX that connects a Blueprint to where it's being used and establishing that schema.

When you edit a Blueprint — because the context is missing — we're not able to show the "extra" contextual fields that are injected on the fly, like slug, date, and taxonomies.

tl;dr solution

Right now you can think of a blueprint having a "belongs to many" relationship.
This PR changes them to a "belongs to" approach. A blueprint should only be used by one thing.

This way Statamic is able to more safely (or at all) assume the proper context of any given blueprint.

Defining the blueprint(s) used by items

Prior to this PR, in order to define blueprints on a collection (for example) you add a blueprints field with an array of blueprint handles.

With this PR, Statamic will instead look for yaml files in a specific location.

resources/
|
|-- blueprints/
    |
    |-- collections/
    |   |-- blog/
    |       |-- basic_post.yaml
    |       |-- art_directed_post.yaml
    |
    |-- taxonomies/
    |   |-- tags/
    |       |-- tag.yaml
    |
    |-- forms/
    |   |-- contact.yaml
    |
    |-- user.yaml

We went back and forth on deciding whether the blueprint should be in the collection/form/etc's yaml file, or a dedicated blueprint yaml file, and think it's still valuable for them to be stored separately

Editing a blueprint allows us to assume context

Now that a blueprint will only be used by one thing, the appropriate contextual assumptions are easy.

Editing the blog collection's art directed post blueprint? We can add those extra fields.

In that screenshot, you might only actually have title and content_blocks in your yaml file, but now you'll see them in the editor. Previously if you wanted to edit the taxonomy fields for example, you had to know "okay, I need a taxonomy field named tags (not tag)". Now it's just there and you'll intuitively be able to tweak its settings.

Embrace fieldsets for reusability

At the moment you can technically reuse blueprints, but after this PR you will not be able to. That's what fieldsets were always supposed to be for, and now that's exactly and specifically all they're for. No more confusion.

Example: If you have two collections with almost identical (or completely identical) sets of fields, you should still have separate blueprints. To stay DRY you can (should?) have a shared fieldset which you import into both.

Keep the blueprints area of the CP

Now that blueprints are directly linked to the thing, you edit them in the appropriate place.
For example, on the collection listing, you can click edit blueprints.

However, the main blueprint section is still useful. It's now a "hub". Just a handy way to quickly jump into the right section.

Collection Entry Links

When editing a collection and toggling "Links" on, it would just add entry_link to its list of blueprints.

Now, when you toggle it on, it'll create a links.yaml blueprint. Toggle it off, it'll delete it.

Migration

You can use this console command to migrate your blueprints:
https://gist.github.com/jasonvarga/ce4f0ad8e3b6d934f8d9da489f2ef64b

• The blueprints array will be removed from content/collection/{colleciton}.yaml and their blueprint yaml files will be moved into resources/blueprints/collections/{collection}/{blueprint}.yaml
• Same for taxonomies
• The blueprint value will be removed from globals, asset containers, and forms. Their blueprint files will be moved into resources/blueprints/globals/{handle}.yaml, etc
• If any blueprints were reused, they'll be duplicated.

Bonus: Events

This PR also adds a bunch of blueprint related events. They replace and improve on the PublishBlueprintFound event, which was only dispatched on the publish form. Now they're dispatched whenever the blueprint is used, which might be on the frontend, etc.

• EntryBlueprintFound
• TermBlueprintFound
• GlobalVariablesBlueprintFound
• AssetContainerBlueprintFound
• FormBlueprintFound

[ebeauchamps]

Does it make sense to have a quick way to duplicate a Blueprint?

[jonassiewertsen]

This is an excellent way of organizing blueprints. An appreciated change, especially for bigger sites with a lot of blueprints!

I would love to see a separation between structure and content in Statamic. Would this be an ideal time to make this breaking change as well?
statamic/ideas#198

[jasonvarga]

@jonassiewertsen We've discussed it internally. It's a good idea. Not in this PR, but hopefully soon.

@ebeauchamps I don't see why not. It's not being added in this PR, but it's a good idea.

[jonassiewertsen]

Sounds promising. Thank you!