3.0.2 breaking changes

Upgrade steps from 2.x to 3.x:

1. Install the newly required Blazy 3.x, if not already.
2. Replace ultimenu canvas classes in page.html.twig, including custom CSS classes with the new ones in your custom theme.
3. Re-save both Ultimenu and block forms, ensure to check the new options as detailed below.
4. Clear cache, or
   

   drush updb 
   drush cr

Details:

Due to a need to access HTML element to fix mobile glitches in 3.0.2, and the addition of new options to support multiple off-canvases, caret and hamburger for any menus in 3.0.3, 3.0.2 - 3.0.3 introduced breaking changes:

1. 3.0.2 -- Mostly the ancestor classes of Ultimenu blocks: body to html, with some clearer BEM. If you are customizing the stylings, please update them accordingly. Be sure to press F5 or CTRL/CMD + R to clear browser cache, and also clearing Drupal cache if changing Twig files at /admin/config/development/performance, or drush cr.
2. 3.0.3 -- The introduction of few new options at admin block such as Use caret, Use as off-canvas, Always use hamburger requires re-configuring and re-saving forms at:
   • Block admin (/admin/structure/block), find the Ultimenu block at header region, and tick the new options.
   • Ultimenu settings (/admin/structure/ultimenu):
     • The global option for off-canvas in desktop and mobile is also moved into block admin as Always use hamburger to support multiple off-canvases.
     • A new option Decouple/ treat Main menu like others is provided as BC to remove, and recommended to enable it.

     Re-configuring and re-saving the forms should bring your off-canvas back. A temporary BC was provided, however re-saving forms is required, in case any misses.

Read more:

• STYLING section for visual details.
• UPDATING if not a new install.
• Aside from breaking changes, Ultimenu added four new dynamic CSS classes to HTML:
  • HTML.is-ultimobile, is hard-coded in HTML, and is updated based on touch detection. Since 3.0.6, use @media (hover: none) {} to avoid FOUC.
  • HTML.is-ultidesktop, is available when is-ultimobile is removed. Since 3.0.6, use @media (hover: hover) {} to avoid FOUC.
  • UL.is-ulticaret, to replace cumbersome :hover with clickable carets at desktop, removed on touch devices, since they always use carets.
  • UL.is-ultihover, to use cumbersome :hover without clickable carets at desktop, removed on touch devices, since they always use carets. Previously UL.ultimenu--hover.

  See detailed usages in css/ultimenu.css.

Replacing touch detection with device width detection

If you want to do more fine grained layouts based on device width rather than touch, this should do:

• Disable CSS aggregation at /admin/config/development/performance
• Press CRTL/CMD + U
• Press CRTL/CMD + F, type ultimenu.css.
• Open the file and other ultimenu CSS files in the browser, find @media (hover: hover) and @media (hover: none).
• Once the file is identified as having those media queries, copy the files into your theme and replace them using libraries-override directive in your theme in line with relevant library definitions. Alternatively use libraries-extend to only override those media queries to reduce complexity.

In your copy or replacement of Ultimenu CSS files, replace:

• @media (hover: hover) with @media all and (min-width: 944px)
• @media (hover: none) with @media all and (max-width: 943px)

Where 943px or 944px is your expected breakpoint to distinguish large from mobile devices.
Now you understand, why 3.x preferred touch detection rather than device width detection. The above replacement samples simplified a lot of pre-3.x media queries works into just few while preserving more accurate displays.

Since 3.0.7, global media queries are moved into ultimenu/css/ultimenu.media-query.css for easy replacements.

Note:

• caret::before vs ultimenu__caret i::after, which holds the icon, this change is to support menu items without links and more complex icon styling. The ultimenu__caret is now used consistently as click handler with or without links. See css/components/ultimenu.caret.css.
• 3.0.2+ no longer supports browser resizing, press CTRL/CMD + SHIFT + M at your browsers, instead. It relies on touch detection to reduce CSS complexity with media queries since the pseudo selector :hover is not available at touch devices anyway. You can always use media queries in tandem for more fine grain styling. Touch device detection with it's new classes in <HTML> tag is more relevant to off-canvas layout or structure, not styling per se.