Grav 1.7 Migration Blueprints

[NicoHood]

Please add: slug: folder-name type: plugin|theme

https://learn.getgrav.org/17/advanced/grav-development/grav-17-upgrade-guide#plugin-theme-blueprints-blueprints-yaml

Could that get clarified, please? What is the slug used for? What about page blueprints or partials? What type should I use in the following usecases:

plugins/ratings/blueprints.yaml                  -> type: plugin, slug: ???
plugins/ratings/blueprints/rating_page.yaml      -> type: ???, slug: ???
plugins/ratings/blueprints/partials/ratings.yaml -> type: ???, slug: ???
themes/quark/blueprints.yaml                     -> type: theme, slug: ???
themes/quark/blueprints/rating_page.yaml         -> type: ???, slug: ???
themes/quark/blueprints/partials/ratings.yaml    -> type: ???, slug: ???

Second question

If your plugins has blueprints folder, initializing it in the event will be too late. Do this instead:

class MyPlugin extends Plugin
{
    /** @var array */
    public $features = [
        'blueprints' => 0, // Use priority 0
    ];
}

https://learn.getgrav.org/17/advanced/grav-development/grav-17-upgrade-guide#blueprints

Do we still need the event code? I am using the event code from here: https://learn.getgrav.org/16/admin-panel/extending#adding-a-custom-page-blueprint-to-a-theme-plugin

public function onPluginsInitialized(): void
{
    // If in an Admin page.
    if ($this->isAdmin()) {
        $this->enable([
            'onGetPageBlueprints' => ['onGetPageBlueprints', 0],
            'onGetPageTemplates' => ['onGetPageTemplates', 0],
        ]);
    }
}

/**
 * Add blueprint directory.
 */
public function onGetPageBlueprints(Event $event): void
{
    $types = $event->types;
    $types->scanBlueprints('plugin://' . $this->name . '/blueprints');
}

/**
 * Add templates directory.
 */
public function onGetPageTemplates(Event $event): void
{
    $types = $event->types;
    $types->scanTemplates('plugin://' . $this->name . '/templates');
}

However I was always wondering why there are 2 more docs with different examples: https://learn.getgrav.org/16/forms/blueprints/example-page-blueprint#in-a-plugin https://learn.getgrav.org/16/plugins/event-hooks#ongetpagetemplates

Maybe those examples should also get updated?

• Is onGetPageTemplates even required? It does not seem to in my usecase, I might be wrong.
• getSubscribedEvents should be replaced by onPluginsInitialized and an isAdmin check, correct?
• The last link has completely different examples for onGetPageTemplates and onGetPageBlueprints. Are those outdated or what is this code used for? I am completely confused here

[mahagr]

The docs talk only plugin/theme blueprint, not other blueprints. Slug and type was added for GPM not to have to guess if your extension is a plugin or a theme.

Nothing else has been changed. I take a deeper look into this when I am looking into documentation.

[NicoHood]

Why is it required to add a slug? Can't grav just parse the folder name itself? this looks duplicated to me.

What about the second question?

[mahagr]

Yes, Grav does use the folder name, but check all the zip files -- there's no good way to figure out the name when you're installing the plugins/themes. This has caused some issues during installation.

[NicoHood]

Alright, that is clear now.

Could you please explain the different between onGetPageTemplates and onGetPageBlueprints and if you should always use both or just one or the other? I will update the docs then accordingly...

[mahagr]

I guess one is for getting blueprints and another is for twig files. Both methods are from the time before streams.

Getting the templates is still relevant as you're not required to define blueprints to have a custom looks. But blueprints should generally be using streams instead.