Document bits of theme-porting wisdom from the Oct 2019 VUG recording

[klonos]

There was this question by @BWPanda about 50min into the recording: https://youtu.be/x8JeTzaC98A?t=3011

@BWPanda:

...this seems like you're hard-coding the order of these things (page blocks/elements) in the theme, rather than letting people do this from the layout (UI).

@jenlampton (emphasis mine, on what needs to be documented):

...all layouts need to "hard-code" all of these things, but they are all always overridable from the layout. ...so, with Backdrop you can always move these things around in the page. And as soon as you put like a tabs block, this thing (the "hard-coded") will disappear. But you absolutely have to put them in the template file also, because if somebody doesn't have that block placed, these things need to be printed to the screen. ...so if you are not particular about where they go, you can put them all in one particular part of the page, and be like: this is the "junk" block, where everything else goes, and you can put a note in your theme, that's like: you might wanna place these things somewhere more sensible.

Coming form Drupal 7, almost all themes had to place all this stuff already (or hopefully they had placed it already), cause it's also required in Drupal 7 same way as it's required in Backdrop, so I am trying to copy what they did; but in Backdrop we do have the option of allowing people to do that ...which was not an option in Drupal 7, unless you added the Block Page Elements (??) module ...or something ...there was something that allowed you to do it ...it was a little hack-y, but it worked.

@BWPanda:

And also to confirm that this only if you use the Moscone layout. If you use a different layout, it's not gonna work?

@jenlampton:

Right, so in order for this theme to support all core layouts (which it should before we release it), we will need to make the same changes to every template file in core. So, there are 10 core layouts; we don't need to support the legacy ones, but there are 10 core layouts ...we would need to take our finished code here when we get it done, and copy and paste for example the position of the page title, the tabs, the actions, into the correct position in the other templates also.

@BWPanda:

Yup, makes sense.

(emphasis mine, on what needs to be documented)

We should capture all this valuable knowledge in https://api.backdropcms.org/converting-themes

[klonos]

cc'ing @jenlampton @stpaultim and @BWPanda

[ghost]

I'm in the process of writing my first contributed Backdrop Layout, and I'm just realising that when I've written layouts previously for my own sites, I haven't added all the extra bits mentioned above, I've just replied on adding them via blocks in the UI. So yes, I'm interested to know and document what exactly needs to be added to the layout template file...

[ghost]

After looking through the core layout templates (all but the legacy ones), I've found that the following things are output in Layout template files in addition to the defined regions:

• 'Skip to main content' link
• Messages
• Page title (inc. prefix & suffix)
• Tabs
• Action links

Update: And I've just confirmed this by looking through the blocks list. All of the above (except the 'skip' link) are blocks and have the following in their description:

Replaces the normal [WHATEVER] on the page with a block.