Evaluate Theming Guide content for Drupal 8 [#2066017]

This task has three parts: the first is to go through the existing content on Drupal 6/7 theming: https://drupal.org/theme-guide/6-7 and identify what, if anything in this section, is also applicable to the section on theming in Drupal 8: https://drupal.org/theme-guide/8

The second part is to look at the D8 section and try and identify any gaps (e.g. we probably need a page on converting D7 themes to Twig).

The third part is to develop a plan for restructuring the Theming Guide so that it's relatively easy to navigate while still avoiding duplication of content as much as possible.

For example, the D6/D7 has a large section on CSS, much of which I suspect is also applicable to D8. Should we move the CSS section (or perhaps most of it) to a top level section, so that it is still discoverable by people who are inside the D8 section? Or is there so much version-specific information that we have to simply fork the existing content into the D8 section and update it?

This is probably a job for a front end person with a reasonable grasp of theming in both D7 and D8.

Comments

Comment #1

LeeHunter CreditAttribution: LeeHunter commented 15 August 2013 at 13:59

Issue tags:

+d8docs

Adding d8docs tag

Comment #2

LeeHunter CreditAttribution: LeeHunter commented 15 August 2013 at 15:31

Quick update, I found that we do have a page for upgrading themes to D8 and I added a cross reference from the main D8 theming page.

Also, I'm wondering whether we need some coverage of HTML 5 changes in Drupal 8.

Comment #3

jenlampton

she / her

CreditAttribution: jenlampton commented 15 August 2013 at 16:46

Title:

Assess Theming Guide content for Drupal 8

» Evaluate Theming Guide content for Drupal 8

Off the top of my head...

CSS
I think the CSS guide may end up being very different for D8. Keeping those other pages D6/D7 specific is probably best, and we should create a new one for D8 that includes all our new crazy class names and all that.

Templates (PHPTemplate vs Twig)
The template overrides section will be quite different

Theme functions
If we end up removing all theme functions from D8 (fingers crossed!) we can remove everything about theme functions from the D8 section :)

theme() vs drupal_render()
We need an item telling people not to use call theme() in Drupal 8. ever.

Preprocess() vs hook_template_suggestion() & hook_template_prepare()

Module devs: We may need to remove everything about preprocess and encourage the use of hook_template_suggestion() & hook_template_prepare() instead
Theme devs: We may need to remove everything about preprocess and encourage the use of hook_template_suggestion_alter() & hook_template_prepare_alter() instead

I'm sure there's more, but maybe that helps you get started?

Comment #4

emmajane CreditAttribution: emmajane commented 17 March 2014 at 23:59

Issue summary:

View changes

The biggest thing I'd like to see documented in the D8 theming guide is a description of how themes are built, using examples from Stark, Bartik, and Seven. By explaining these three themes we'll cover: .yml files, .twig files, .theme files, breakpoints, regions, CSS, etc.

Comment #5

pixelmord CreditAttribution: pixelmord commented 26 March 2014 at 13:31

I think with that we have so much changes, that it makes no sense to add anything about D8 to the D6/7 pages but cross-referencing links to and from the existing D6 and D7 theme documentation.

I still remember the time when I myself needed the documentation for the former versions and got seriously confused with the mix (sure there are better pages and worse..), also the comments being mixed regarding versions can a lot of times be the opposite of useful.

I would recommend that everything should be covered under the Drupal 8 Theming guide (https://drupal.org/theme-guide/8) and links for reference should be pointing to and from the respective sections of the former versions. With that we would have a single point of entry.