Custom blueprints in themes—is this the right way to get it work?

Hi everyone.

I had a hard time making blueprints work in themes. Technically my problem is solved, but I don't know if I solved it the good way.

According to the documentation, blueprints in themes (here, for pages) should work out of the box. But, if I place my blueprint to extend the page modification form at my-theme/blueprints/pages/default.yaml, it didn't work. Like, there is no error message at all but the blueprint is ignored.

By digging really deep into the blueprint & themes-loading code, I found that I could force-register the blueprints in Grav by adding this to my template configuration file (my-theme/my-theme.yaml):

# Required for the theme blueprints to work. (Undocumented??)
streams:
  schemes:
    blueprints:
      type: ReadOnlyStream
      paths: ['themes://my-theme/blueprints']

And, well, it works! My blueprint is correctly recognized, and everything is ok. Or, is it? Is this way of registering the blueprint a good one? It's documented nowhere as far as I know, and I don't know if I used a strange and unmaintained (or deprecated) way to do so. Either that or the documentation is missing something (or I am).

Thank you for your support, and (as I'm here) for this excellent piece of software called Grav (theses problems excepted, I had a really good time working with it!).

Hi @AmauryCarrade, that location for the Blueprint does not look right to me. Try moving the blueprint to /my-theme/blueprints/default.yaml and let me know if it works.

You can see a working example of this in my Open Course Hub Bootstrap theme (which is actually an inherited theme too): https://github.com/hibbitts-design/grav-theme-course-hub-bootstrap/blob/master/blueprints/default.yaml

Hi, thanks for your answer!

Indeed I tried that, I saw that suggestion on another topic. And I tried again, removing the streams entry of the my-theme.yaml file and updating the directory structures like you said.

And… no luck. My blueprint, despite being valid, is ignored (and not even registered, in fact, if I check that with some error_log in the core).

Do you have any idea? I don't know what I'm doing wrong, it's a little bit weird. At least it works with my trick, but I would rather use an official and supported way of doing things.

Thanks again for your help :) .

<details>
<summary>I hidden a lot of details about my structure and files in there</summary>

Just to be sure, here is my directory structure (the one not working but like you said):

$ tree -L 2 --dirsfirst
.
├── blueprints
│   ├── default.yaml
├── css-compiled
│   ├── […]
├── fonts
│   ├── […]
├── images
│   ├── […]
├── scss
│   ├── […]
├── templates
│   ├── […]
├── CHANGELOG.md
├── LICENSE
├── Makefile
├── README.md
├── blueprints.yaml
├── my-theme.php
├── my-theme.yaml
├── screenshot.jpg
└── thumbnail.jpg

And the my-theme.yaml:

enabled: true

# Required for the theme blueprints to work. (Undocumented??)
# streams:
#   schemes:
#     blueprints:
#       type: ReadOnlyStream
#       paths: ['themes://nebulius/blueprints']

header:
  title: ''
  tagline: ''

And just to be sure, my default.yaml file starts with that:

'@extends':
  type: default
  context: blueprints://pages

form:
  fields:
    tabs:
      fields:
        content:
          fields:
            …

(but the @extends part was

@extends:
  '@parent'

before, and with that and the weird streams configuration it works).

</details>

Per your directory-tree above, this is correct, and default.yaml should be active on page’s whose template use default.html.twig - it will not, to my knowledge, extend to all template-types.

Oh, this may explain why it does not work: I was testing on an item page. Indeed by renaming the blueprint to item.yaml, it works without the explicit streams' definition.

This being said, I need to add a blueprint for default and all sub-types (and I'll have to combine this with other-types-specific blueprints later). So, except if there is another way, and considering that explicating the streams is all ok, I'll stay on that.

The non-heritance thing could have been documented, I think (except if I missed that part), and why not the advanced way to register streams (but it seems to be pretty internal so I understand why it isn't on the public themes' documentation…).

Thank you for these clarifications!