Problem/Motivation

There are a number of changes that may need to be made to update custom AT-based themes to the new 1.0 release. This issue is designed to document some of them. If you have more suggestions, please add them!

Disclaimers:

  • This issue is not a guide, more a place to compare notes and share potential solutions.
  • Sites may be upgrading from different versions of AT, so some of the tips here may or may not apply.

This issue assumes:

  • You have a custom theme based on Drupal 8 Adaptivetheme that was created for a version of Adaptivetheme prior to the full 8.x-1.0 release.
  • You have a site that theme is running on.
  • You would like to update that theme and site to the latest version of Drupal core and Adaptivetheme 1.x.

Preparatory steps

Before attempting to upgrade your custom theme from a prior version in the 1.x branch to AT 8.x-1.0:

  • Do a complete site backup.
  • Working with a development version of your site that you can throw away as needed, update to the latest stable release of Drupal core 8.3.
  • If you are using Display Suite, update to the latest recommended release (in the 3.x branch).
  • Update Adaptivetheme and AT Tools to the latest stable releases in the 8.x-1.x branch. Note that this step may appear to break your site. This issue is designed to help you work through the various changes you may need to make in your custom theme and elsewhere to bring your site back up.
  • (optional) Enable twig debug mode so you can see which templates may be involved in specific errors.

You may need freshly generated code for your custom theme. To get it:

  • On a test site where your custom theme is not installed (for example, a fresh install of Drupal core), install the current version of AT Tools that's right for your theme version (the latest 1.x release).
  • Generate a new version of your theme, giving it the same name as your current custom theme. This will give you fresh files you can use in some of the suggested solutions below.

Issues and potential solutions

Here are some errors you may get when updating an AT theme from a prior version in the 1.x branch to AT 8.x-1.0. They're arranged roughly chronologically. That is, if you hit earlier issues, you need to resolve them before you'll see the later ones.

PHP error mentioning layouts

PHP error mentioning missing classes

  • Error: you get a PHP error mentioning a missing class, such as Drupal\at_core\Theme\ThemeConfig
  • Source: the code in Adaptivetheme Core has changed and some classes have been removed.
  • Potential solution: you may need to update custom code in your theme, removing usage of classes that were removed from at_core. In the example given, you'd need to remove this line use Drupal\at_core\Theme\ThemeConfig; and also update any code that was using that class.

Page content missing/blank page

  • Error: you get a page that appears empty.
  • Source: the structure of some templates used in Adaptivetheme has changed.
  • Potential solution: replace your templates with fresh copies. Tip: if you see odd content or missing items, look at the page markuip to determine which template may be involved and either delete or replace that template in your custom theme. Specifically:
    • In your custom theme, delete the file templates/generated/page.html.twig and replace it with the version you generated fresh using the current version of AT Tools. Clear caches.
    • If you have a custom override in your custom theme of the html.html.twig template, try removing it so that the version in at_core will be used.

Broken AT layout

  • Error: A page using an AT layout renders but the layout is broken.
  • Source: The markup used for layouts has changed and your custom theme has the old versions.
  • Potential solution: In your custom theme, delete the folder styles/layout_plugin and replace it with the version you generated fresh using the current version of AT Tools.

Visual regressions

  • Error: While the custom theme renders without cod errors, there are visual regressions such as changed margins, alignment of header items, and so on.
  • Source: The AT Core markup and SCSS/CSS has changed.
  • Potential solution: In your custom theme, update your SCSS/CSS.

Comments

nedjo created an issue.

fkelly12054@gmail.com’s picture

@nedjo, thanks for all you have done here and for your proposed patch.

I was experimenting with AdaptiveTheme before 8.3 came out. It's not clear to me that the juice is worth the squeeze to continue with this theme. It appears that the author has abandoned it, there has been no comment from him and certainly no commits since early March and especially no comment since 8.3 of Drupal core came out. If I was skilled and dedicated enough to have created and maintained a theme such as Adaptivetheme (an enormous undertaking) and then the core developers had "pulled the rug" out from under me by breaking compatibility with the layout_plugin module, I'm not sure I'd be in any rush to fix things either. Incidentally, the main page for AdaptiveTheme lists two stable releases of the 8.x code: 8.x-2.0 and 8.2-1.0. Both were committed on the same day: March 3, 2017.

Oops, I see that https://www.drupal.org/node/2879212 (What's up with the support) has been posted while I was typing this. I think we are all on the same page and that we all have tremendous respect and thanks to Jeff for having created and supported this theme in the first place.