Need tutorial on how to convert themes to BD from D7

[docwilmot]

Just did my first theme conversion of the Clean theme https://www.drupal.org/project/clean_theme. See it here at http://wilmurt.com/
There are a few things which need to be mentioned for persons hoping to do that as I'm sure you know. These were my personal thoughts:

• Overall it wasnt terribly difficult at all
• $block_html_id is not found but not documented as missing
• $attributes and $classes need wrapping in backdrop_attributes() and implode() respectively
• The main system menu doesnt have a <nav> tag
• The site name in the header somehow is wrapped in <h1> on the front page but <strong> elsewhere
• Comments on by default on basic page; it should be off I think
• Template documentation blocks need the available variables corrected. Example $picture is not available but is still documented.
• Most important, on creating a new layout, the content panel cant be found.

Clean came with a slider on the front page which is baked into the page.tpl.php. Since this template is now individual layout files, how does a them provide a slider now? Override layout templates? Provide a layout-front-page.tpl.php? This was a head-scratcher, which I still havent figured.

Finally if I wanted to list this theme on BD contrib page, whats the procedure?

I will try to put these thought into a coherent document eventually, but just wanted to record this here to highlight the issues.

[quicksketch]

Finally if I wanted to list this theme on BD contrib page, whats the procedure?

Although you've already proven your knowledge, the official procedure is to apply for an account at https://github.com/backdrop-ops/contrib. :)

Comments on by default on basic page; it should be off I think

Agreed, I thought we turned it off but looks like they're indeed on.

Most important, on creating a new layout, the content panel cant be found.

Could you elaborate?

Since this template is now individual layout files, how does a them provide a slider now?

I think the only options here are to override the header.tpl.php, or the block--system-main.tpl.php file, neither are really ideal substitutes. This may be a result of our separation between layout and theme, which may have resulted in a separation between functionality and theme as a side-effect.

[cellear]

The slider provided by Clean Theme seems like the sort of thing that should not be provided by a theme at all. It's functionality, or at the very least, layout. If you built a site in Clean Theme, you wouldn't be able to easily switch to another theme.

Of course, it's open source, and we can't stop anybody from doing what that want, but...this seems like something that we don't particularly want to encourage. If a site builder wants to include Nivo Image Slideshow in their site, the "preferred" way would be for them to grab a module for the functionality, then drop the pane/block/whatever into a layout. Is that right, or am I missing something?

[docwilmot]

Could you elaborate?

The "Main page content" block is absent from the "content panel " when you click "add new layout" and if you click "add block" its not listed among the other blocks. There is no way to add main page content to a new user-defined layout.

[docwilmot]

seems like the sort of thing that should not be provided by a theme at all

Technically that may be a reasonable POV, but every CMS has many (probably the majority} themes/templates which provide sliders or front page images these days. Users will expect this, and themers will expect to be able to do it.
Point is we need to have a suggestion for Best Practice in providing sliders/images on your website. I'd say having Nivo etc as a requirement may be a way, but it would be nice if we could present a way to do it without a module requirement. I cant think of a way.

[quicksketch]

There is no way to add main page content to a new user-defined layout.

Ah! Yes that's normal behavior. The "main page content" block only exists if you're overriding an existing menu path. So if you were to override "node/1" for example, the "main page content" would exist. But if you create a layout at "my-custom-path", the main page content block doesn't exist because it wouldn't contain anything. So my suggestion of overriding block--system-main.tpl.php isn't going to work.

Technically that may be a reasonable POV, but every CMS has many (probably the majority} themes/templates which provide sliders or front page images these days. Users will expect this, and themers will expect to be able to do it.

Yep, I think you're right that the expectation is there that the theme can add functionality, even if that's been somewhat discouraged in the Drupal community, it's still been possible. Perhaps we could make the homepage modifiable through some dedicated template... I'm not sure about it.

[docwilmot]

So if you were to override "node/1" for example, the "main page content" would exist

I'm not finding this, but I'll raise an issue in the right place.
But, to return to the main point of this post, we need docs for this stuff.

[ghost]

I'd like to add my 2 cents regarding functionality in themes. I personally hate it when themes provide functionality like a slider. No offence, but themers aren't the best coders. I find implementations are often not flexible (they're made to work a certain way and that's it) and things that should be options/configurable are hard-coded.

I put my vote behind separating functionality & design. As @cellear said, themes should be interchangeable. Now that themes are no longer responsible for defining regions, there's no reason you can't easily switch themes with little-to-no changes to a site necessary.

[quicksketch]

I too like the new separation between themes and layout, and the resulting separation between themes and functionality, but it really is the case a lot of the time that the design and functionality go hand-in-hand, for example a theme intended for a brochure site is different than the theme for an e-commerce site.

I think we'll need to solve this old problem in a new way with Backdrop. Themes are likely to become "skin-only" and add-on functionality might be through new, unconventional means. One option is bundling a directory of config files to pre-configure a layout, new blocks, a slideshow, rotators, etc. With the right configuration, a theme wouldn't need additional modules for something like a rotator, since it can just convert an <ul> into a rotator with the right CSS/JS. Themes don't have the ability to bundle config in an automatic way currently (and I'm not sure they should), but somehow packaging config is an approach that is available to us that hadn't been an option in D7.

[danny-englander]

I'm just curious about this:

Now that themes are no longer responsible for defining regions...

So how and where do we define regions for a theme?

[ghost]

So how and where do we define regions for a theme?

Through Layouts' template files. Here are the ones included in Backdrop core: https://github.com/backdrop/backdrop/tree/1.x/core/layouts

And note that you're creating regions for layouts, not themes.

[danny-englander]

@BWPanda thanks, interesting! This seems similar to how Omega 4.x does it. I like it.

[docwilmot]

Seriously though, @quicksketch @jenlampton @cellear, we cant launch in 13 days and have talent like @danny-englander still unable to discover about basic things like defining regions. To the original point of this issue, and excuse the nagging, docs pages soon please?

[jenlampton]

@docwilmot I think we need to do two things:

1. on backdropcms.org we need to explain to people the basic building blocks of a Backdrop site: Modules, Themes, and Layouts. This is the what of backdrop. We need to clearly explain the difference between a theme and a layout, and what's responsible for what. https://backdropcms.org/layouts - was missing, and now needs some love

2. on api.backdropcms.org we need to explain the how for Backdrop, from the coder's perspective. For this, I've started a new book called "Developer Documentation" https://api.backdropcms.org/documentation - new, and also needs some love

As for the launch of Backdrop CMS, our priority is to get Backdrop out on Jan 15th. After we get backdrop out, then our priority will shift back to the community tools that are needed to support it. First things first :)

[klonos]

https://backdropcms.org/layouts needs a better title IMO. How about "Build with Blocks and Layouts". I realize this puts blocks and layouts in the same documentation section, but I think they need to be explained together anyways. A more detailed "place Blocks in the regions created by Layouts" I guess.

[jenlampton]

Love it :)

[danny-englander]

I was looking at the docs and theme structure on https://api.backdropcms.org/themes and I am wondering if a theme can declare a layout? I am envisioning a layouts folder in my theme folder that then can be used in the layouts management page. I just don't want to go down a rabbit hole before I start a theme conversion.

[jenlampton]

Hi @danny-englander! In short, no.

The whole point of separating layouts from themes is so you can to change your theme without breaking your site, and so that you can easily use a different layout on any page (the home page, for example, often uses a different layout than the rest of the site)

If your site needs a special layout then you'll need to create both a layout and a theme. The CSS for the layout will go in the layout (so that it can work with any theme) and the CSS for the theme will go in the theme (so that it can work with any layout).

You can then change your "default" layout to use the new layout you have created, and you'll see it on every page of your site.

[danny-englander]

Hi @jenlampton, so it sounds like I can declare a layout in a custom theme? I am picturing this in my theme folder:

|__mytheme_two_column (folder within my theme's root)
| |____layout--mytheme-two-column.tpl.php
| |____layout.css
| |____preview.png
| |____mytheme_two_column.info

[ghost]

The CSS for the layout will go in the layout (so that it can work with any theme) and the CSS for the theme will go in the theme (so that it can work with any layout).

Loving this new separation! 👍

[jenlampton]

@danny-englander No. Layouts and themes are completely separate and can not be packaged together. (That would defeat the point of the separation, and your site would still break if you changed your theme)

Layouts are a new concept in Backdrop. Where Drupal had modules and themes, Backdrop has modules, themes, AND layouts. For an example of the anatomy of a layout see the core/layouts folder and the three layouts within.

All you can do to a layout in a theme is override the *.tpl.php file, or .css (just like you can with anything else). For example: you may be able to get away with using the core two-column layout and overriding the CSS to make the columns different widths. But if you need a four-column layout, you'll need to add your own in /layouts/four_col.

Here's an example directory structure (abbreviated)

backdrop
 - core/
 - - layouts/
 - - libraries/
 - - modules/
 - - themes/ 
 - layouts/
 - - four_col
 - libraries/
 - - ckeditor
 - modules/
 - - custom/
 - - - lots
 - - contrib/
 - - - lots_and_lots
 - themes/
 - - customtheme
 - settings.php

[danny-englander]

@jenlampton - that's perfect, thank you!

[jenlampton]

Converting tutorial is located here: https://api.backdropcms.org/converting-themes Closing this issue.