Skip to content

Upgrading

Update to 8.x-1.10 or later and run the database updates:

drush updatedb

Attribute name rules (8.x-1.8 to 8.x-1.10)

Since 8.x-1.8 attribute names must pass the rules described in Allowed attribute names. Current Drupal core drops other names from menu links, so these attributes no longer got rendered anyway. Update 8004 runs only once, so what happens to existing configuration depends on the release it ran in:

Release What happens to invalid names
8.x-1.8 Update 8004 deletes every invalid definition. This includes all container_* attributes, because the prefix was checked as part of the name, and names whose only problem is an underscore.
8.x-1.9 Update 8004 checks names without the container_ prefix, so valid container attributes are kept. Names with underscores are still deleted. A post update restores container attribute definitions still used by menu links (#3590635).
8.x-1.10 Update 8004 renames names with underscores to hyphens. A post update renames the values stored on menu links and restores definitions deleted by earlier releases (#3590636).

The diagram shows update 8004 as of 8.x-1.10, which runs for sites updating from 8.x-1.7 or earlier:

flowchart TD
    Name["Configured attribute name"] --> Valid{"Valid without<br>container_ prefix?"}
    Valid -->|yes| Keep["Kept"]
    Valid -->|no| Hyphen{"Valid after replacing<br>_ with -?"}
    Hyphen -->|no| Delete["Deleted"]
    Hyphen -->|yes| Exists{"Hyphenated name<br>already defined?"}
    Exists -->|yes| Delete
    Exists -->|no| Rename["Renamed"]

Underscores in attribute names

From 8.x-1.10, data_menu_color becomes data-menu-color and container_menu_color becomes container_menu-color. The underscore in the container_ prefix is part of the module's syntax and stays.

  • Configuration: on sites updating from 8.x-1.7 or earlier, update 8004 renames the definition and keeps its label, description, and options. If the hyphenated name is already defined, the underscore definition is deleted instead. Sites that already ran update 8004 in 8.x-1.8 or 8.x-1.9 get the definition back from the post update, see below.
  • Menu links: the menu_link_attributes_post_update_migrate_underscore_attributes post update renames the stored values on every menu link and translation. If a link already has a value under the hyphenated name, that value is kept and the old one is dropped.
  • Front end: every rename is logged as a warning in Reports > Recent log messages and printed by drush updatedb. Update CSS selectors, JavaScript, and Twig templates that target the old names.

Coming from 8.x-1.8 or 8.x-1.9

Sites that ran update 8004 in 8.x-1.8 or 8.x-1.9 already lost the definitions of attributes with underscores, and in 8.x-1.8 also of container attributes. The values stayed on the menu links. Two post updates add definitions back for attribute names still found on at least one menu link:

  • menu_link_attributes_post_update_restore_container_attributes (8.x-1.9) restores valid container attributes.
  • menu_link_attributes_post_update_migrate_underscore_attributes (8.x-1.10) restores attributes with underscores under their hyphenated name.

Attributes no menu link uses are not restored. Restored definitions are empty, except container_class, which gets its default label and description back. Labels, descriptions, options, default values, and field types are gone, so the fields show up on the menu link form with a generated label and as plain text fields. Re-add the settings on the configuration page, for example from a configuration export made before the update:

attributes:
  data-menu-color:
    label: 'Menu color'
    options:
      red: 'Red'
      blue: 'Blue'

8.x-1.9 also added an empty container_* duplicate for attributes defined without the prefix but with container: true. The 8.x-1.10 post update removes those duplicates.