Upgrade to 5.x

Site-specific theme updates

1. Upgrade Composer packages

Run the following commands to upgrade composer packages to the appropriate versions:

• fin composer require pega/pega_bolt:8.x-5.x-dev
• fin composer require pega/bolt-release:^5.0
• fin composer require pega/pega_bolt_theme:8.x-5.x-dev
• fin composer update pega/pega_cd
• fin composer update pega/pega_user_image

2. Upgrade Node

Update the version of Node used in your Drupal site to 14.18.1 (most sites are currently on 12.12.0). The node version can be found in 3 places:

1. .docksal/cli/Dockerfile
2. docroot/themes/custom/[DRUPAL_THEME]/.nvmrc
3. .gitlab-ci.yml (it may not already appear here-- if not, it should be added as a variable called NODE_VERSION in the variables section.)

Then, run the following to reset the cli container and install the new version of Node:

fin reset cli

Optional for most Drupal developers - to upgrade Node outside of your Docker container:

• nvm install 14.18.1
• nvm use 14.18.1
• nvm alias default 14.18.1

If you are not already using nvm see Node configuration docs.

3. Rebuild your theme's front-end code

From your project root, run:

• fin fe-build (or whatever command builds your theme-- on pega.com, for example, this is fin exec make theme)
  • You may be prompted to enter your GitLab credentials to create a token

4. Update icon paragraph type

Update the configuration for the icon paragraph type (used in content pages) to match the config in pega_bolt_icon/config/install. To make the process easier, you can run the following drush commands to update and export configuration the icon paragraph type:

fin drush ev "\Drupal::service('config.installer')->installDefaultConfig('module', 'pega_bolt_icon');"
fin drush cex -y

Commit the newly exported configuration from your site's config/sync directory. IMPORTANT: You should review the changes manually to confirm that they all make sense. For example, if your site has made customizations to the icon paragraph type, be careful not to destroy them here.

Note: If your site supports custom hex color for icon paragraphs (many sites never did), they need to be replaced with brand colors. Contact the Bolt team for further details.

5. Adjust header and footer

The footer is now coming from Bolt. The header is already coming from Bolt if you're on Bolt 4, but the top menus have been significantly updated. See https://boltdesignsystem.com/pattern-lab/?p=components-page-header-example-pegaworld.

If you are using region--header.html.twig and region--footer.html.twig from the base theme, then this will mostly work automatically. If you are overriding those files in your sub theme, you should try to remove the overriding files. An example of that can be found here: https://gitlab.com/pegadigital/pa/pegaacademy/-/merge_requests/1300. You may need to rename menus in configuration, for instance, and/or make modifications in preprocessing (such as path to the logo). If you have trouble with this, please ask Remy or Andrew for help.

Once you are using the base theme templates, there are two additional tweaks:

• Manually remove the Contact link from the sites user menu (no longer needed, moved to its own menu in the header)
• The Sites and Contact menus are now mostly hard-coded. If your site has a custom path for a link URL, you can set the path in preprocessing, either THEME_preprocess_pega_bolt_theme_related_sites_nav() or THEME_preprocess_pega_bolt_theme_contact_nav(). For example, if your site has its own contact page, you could do this:

/**
 * Implements THEME_preprocess_pega_bolt_theme_contact_nav().
 */
function pegawww_theme_preprocess_pega_bolt_theme_contact_nav(&$variables) {
  $variables['contact_href'] = Url::fromURI('internal:/contact-us')->toString();
}

6. Make front-end updates

At this point, you may still see errors because Twig templates reference old icon names. The following steps should fix the errors.

Icon Component

1. Search your subtheme for any instances of the @bolt-components-icon component and replace with the @bolt-elements-icon element.

Note: See all search results for "components-icon" in the "Pega Digital" codebase (ignore the Pega Core Theme results).

2. Double-check the Icon's "name" prop value to make sure it was not retired. For example, if there were an Icon component using the name "global":

{% include '@bolt-components-icon/icon.twig' with {
  name: 'global',
} only %}

The "name" value must change to "globe":

{% include '@bolt-elements-icon/icon.twig' with {
  name: 'globe',
} only %}

Refer to the Icon Remapping document found on the DS-502 ticket for more information.

3. Update icons that use the background prop.

We removed the background prop when upgrading the Icon component to the Icon element. We have introduced a new Shape Element to handle the icon background. Here's how you used to set a background on an Icon component:

{% include '@bolt-component-icon/icon.twig' with {
  name: 'globe',
  background: 'circle',
} only %}

Now, you must wrap the icon in a background shape like so:

{% set icon %}
  {% include '@bolt-elements-icon/icon.twig' with {
    name: 'globe',
  } only %}
{% endset %}

{% include '@bolt-elements-shape/shape.twig' with {
  content: icon,
} only %}

Note: The Shape Element will render as a circle by default. Refer to the Shape Documentation for more information.

4. Remove the aria-hidden attribute anywhere it was manually added to an Icon component. This attribute is automatically added when you use the Icon element. If you see the following example, remove attributes:{ 'aria-hidden': 'true' }.

{% include '@bolt-component-icon/icon.twig' with {
  name: 'globe',
  attributes: {
    'aria-hidden': 'true'
  }
} only %}

5. Replace Icon web components with "element" HTML.

If you find an example of a pure Icon web component, i.e. <bolt-icon> in plain HTML, please replace with the HTML version of the Icon element.

In PHP, you can utilize the UI Patterns module with the renderer service. You just need to create a render array and include the name of the icon you wish to use.

The HTML version would require you finding the icon's <path> and paste it within the <svg> tag. Refer to the Icon Element Docs page for examples (you can inspect in the browser for the HTML output of these icons).

For example, you can replace the Pega Announcement icon with the following code:

Old Icon Web Component example

<bolt-icon name="pega-announce"></bolt-icon>

New Icon PHP example

$renderable = [
  '#type' => 'pattern',
  '#id' => 'icon_element',
  '#fields' => [
    'name' => 'pega-announce',
  ]
];

$icon = \Drupal::service('renderer')->render($renderable);

New Icon HTML element example

<svg class="e-bolt-icon" aria-hidden="true" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
<g><path d="m22.15 3.75a1 1 0 0 0 -1.15.34c-.13.17-3.21 4.16-10.27 4.16h-5.79a5 5 0 0 0 -5 5v1.75a5 5 0 0 0 3.68 4.8c.23 1.9 1.18 6.94 5 9.73a1 1 0 0 0 1.29-.09l2.09-2.07a1 1 0 0 0 .3-.79 1 1 0 0 0 -.42-.74 8.26 8.26 0 0 1 -3-5.83h1.87c7.07-.01 10.15 3.99 10.25 4.14a1 1 0 0 0 .8.41 1.06 1.06 0 0 0 .31 0 1 1 0 0 0 .69-1v-18.87a1 1 0 0 0 -.65-.94zm-12.31 22.94-.71.7c-2.39-2.2-3.2-5.66-3.46-7.38h1.23a10.67 10.67 0 0 0 2.94 6.68zm-4.9-8.69a3 3 0 0 1 -3-3v-1.75a3 3 0 0 1 3-3h4.79v3 1.75 3zm15.89 3.2a15.76 15.76 0 0 0 -9.07-3.2v-7.78a15.76 15.76 0 0 0 9.07-3.22z"></path><path d="m28.31 14.18a4.55 4.55 0 0 0 -2.93-4.24 1 1 0 0 0 -1.29.58 1 1 0 0 0 .58 1.29 2.53 2.53 0 0 1 .1 4.7 1 1 0 0 0 -.54 1.31 1 1 0 0 0 .93.61.84.84 0 0 0 .38-.08 4.51 4.51 0 0 0 2.77-4.17z"></path><path d="m26.66 6.55a1 1 0 0 0 -.66 1.87 6.19 6.19 0 0 1 4 5.76 6.13 6.13 0 0 1 -3.76 5.66 1 1 0 0 0 .39 1.93 1 1 0 0 0 .38-.08 8.15 8.15 0 0 0 -.29-15.14z"></path></g>
</svg>

Note: For more information on Icon Element schema please refer to the Icon Documentation page.

Video Component

We removed the deprecated Bolt Video Component from the Bolt Design System. The vast majority of these conversions were done previously when the Brightcove video player was refactored last year. But just to make sure there are no regressions, perform the following tasks in the Drupal codebase and database:

• Search for any @bolt/components-video dependencies, since this package doesn't exist anymore we need to remove this.
• Double-check to make sure that no examples of the <bolt-video> can be found. If any are found please replace with the new pattern:

{% set video %}
  <video-js
    data-account="[BRIGHTCOVE ACCOUNT]"
    data-player="[VIDEO PLAYER]"
    data-embed="default"
    data-video-id="[VIDEO ID]"
    controls
    class="c-base-video"></video-js>
{% endset %}

{% include '@bolt-components-ratio/ratio.twig' with {
  children: video,
  ratio: '16/9'
} only %}

Note: Reach out for any questions on how to convert any videos in the ds-dev-help Slack channel.

Dropdown Component

In the Drupal codebase and data base perform the following tasks:

• Search through the repository for any instances of the @bolt/components-dropdown component and remove them.
• Search for any examples of <bolt-dropdown> and remove them.

CSS Updates

Removal of bolt-theme()

Note: See all search results for "bolt-theme" in the the "Pega Digital" codebase (ignore the Pega Core Theme results).

In the Drupal codebase and database perform the following tasks:

• Double-check that there are no examples of the deprecated bolt-theme() SASS function.
• All examples of --bolt-theme-* CSS vars are converted to the new --m-bolt-* vars, See CSS Vars docs. Most of the conversions are pretty straight forward, for example --bolt-theme-secondary gets changes to --m-bolt-secondary (notice the "prefix" --bolt-theme is targeted with this change).