Toolbar Themes is a contributed module for Drupal 8. It includes a number of stylised themes that apply only to the Drupal 8 Toolbar.

The main purpose of this module was to replicate the old D7 Admin Menu style, since D8 cores toolbar takes up a lot of screen realestate and for power users the icons and most of the tabs are not required.

Any module or theme can provide a Toolbar Theme. This is a brief guide on how to create your own Toolbar theme.

File Anatomy

[provider].toolbar_themes.yml.

YML definitions for themes. The provider is your theme or module.

[provider].libraries.yml

Each theme must declare at least two libraries, one for icons and one for everything else. The icons library is only loaded if the user selects the option "Show icons" in the modules UI settings. The provider is your theme or module.

CSS

AT least two CSS files are required, one for icons and one for everything else.

Templates

Your theme or base theme can provide template overrides for the toolbar and toolbar menu. Preprocess functions are automatically registered for each template.

Icons

Icons are loaded by your theme, it's entirely up to you how you want to do this. The default base theme uses grunticon.

[provider].toolbar_themes.yml

Modules and themes are scanned for this file, if found this file is parsed and cached in the database.

A keyed array of theme definitions.

Required:

• key: theme machine name
• label: string, used in forms.
• libraries: mapping, name of libraries declared for this theme in the providers libraries.yml

Optional:

• hidden: value can only be true, otherwise simply omit. Useful for base themes you don't want to show in the form.
• version: Normal version string.
• description: string, used for screen shot alt. Include if you have a screen shot.
• path: path to theme, relative to the provider root. If you have templates, icons or a screenshot this is required!
• screen_shot: path to screen shot, relative to the path value.
• template_toolbar: define if you want to include a template and preprocess override for the toolbar template, path must be relative to the path value.
• template_toolbar_menu: define if you want to include a template and preprocess override for the toolbar menu template, path must be relative to the path value.
• icons: path to a directory of icon files, path must be relative to the path value.
• base_theme: machine name of the base theme.

Here we define two themes: a base theme and a child theme (these are from toolbar_themes.toolbar_themes.yml).

toolbar_themes_base:
  label: "Toolbar Themes Base"
  hidden: true
  version: 8.0-1.x
  description: "A minimal base theme for Toolbar"
  path: themes/base
  template_toolbar: templates/toolbar-themes--base-toolbar
  template_toolbar_menu: templates/toolbar-themes--base-menu
  icons: grunticons/processed
  libraries:
    base: toolbar_themes/toolbar_themes_base.base
    icons: toolbar_themes/toolbar_themes_base.icons

toolbar_admin_menu:
  label: "Admin Menu"
  version: 8.0-1.x
  description: "Drupal 7 Admin Menu module style."
  path: themes/admin_menu
  screen_shot: screenshot.png
  base_theme: toolbar_themes_base
  libraries:
    base: toolbar_themes/toolbar_admin_menu.base
    icons: toolbar_themes/toolbar_admin_menu.icons

[module/theme name].libraries.yml

Define at least two libraries - one for the base and one for icons.

Note we define dependancies, e.g. toolbar_themes/toolbar_themes_base.base unless you want to re-write all of Toolbars CSS, and Admin Toolbars CSS as well, I highly recommend using these libraries.

# Base theme.
toolbar_themes_base.base:
  version: 8.0-1.x
  css:
    theme:
      themes/base/base_module.css: {}
      themes/base/base_handles.css: {}
      themes/base/base_theme.css: {}

toolbar_themes_base.icons:
  version: 8.0-1.x
  css:
    theme:
      themes/base/base_icons.css: {}

# Admin Menu theme.
toolbar_admin_menu.base:
  version: 8.0-1.x
  css:
    theme:
      themes/admin_menu/admin_menu_theme.css: {}
  dependencies:
    - toolbar_themes/toolbar_themes_base.base

toolbar_admin_menu.icons:
  version: 8.0-1.x
  css:
    theme:
      themes/admin_menu/admin_menu_icons.css: {}
  dependencies:
    - toolbar_themes/toolbar_themes_base.icons

Toolbar Themes base theme requires one other library for loading the icons, and because all themes that define a template have a preprocess function you can load additional assets such as this quite easily.

Templates and Preprocess

If your theme or base theme defines templates these are automatically added to the theme registry and will be loaded.

The template name is exactly as you define in the themes definition, e.g.:

toolbar-themes--base-toolbar becomes toolbar-themes--base-toolbar.html.twig
toolbar-themes--base-menu becomes toolbar-themes--base-menu.html.twig

The preprocess function will have this naming convention:

[provider]_preprocess_[template]

For example, for the above templates, respectively:

toolbar_themes_preprocess_toolbar_themes__toolbar()
toolbar_themes_preprocess_toolbar_themes__menu()

CSS

Remember that Toolbar Themes module totally nukes all of Drupal cores Toolbar CSS files, entirely, and sticks everything in it's own base theme. Use this base theme if you're happy with the icons and generally look and behaviour, otherwise define your own base theme and rewrite the CSS to suite.

The Admin Menu and Seven toolbar themes have a nice _variables.scss file that makes it very easy to create new color schemes and adjust padding etc.

Icons

Icons in Toolbar Themes themes are very different to Drupal cores Toolbar icons - I have done away with background-image SVG and instead use JS to embed SVG directly in the markup. This allows us to style the SVG icons with CSS. The module uses Grunticon to do this.

Not all icons are embedded SVG however. Some use an icon font - the orientation toggles, sub-menu indicators (both in the toolbar vertical orientation and in Admin Toolbar drop menus), and one special case for the Manage Tab hamburger when the tabs are removed. All of these require negative text-indent to hide the text labels and it was far easier to just compromise and use an icon font rather than embedded SVG for these cases.

The icons are provided by Toolbar Themes base theme. Define this as a dependancy if you want to use the same icons.

And thats really about it, good luck, see you in the issue queue if you have a question.