Upgrade to 5.x

Site-specific theme updates

Composer package versions

Run the following commands to update composer to the appropriate package versions:

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

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 2 places:

1. docroot/themes/custom/[DRUPAL_THEME]/.nvmrc
2. .docksal/cli/Dockerfile

To upgrade Node outside of your Docker container (optional for Drupal devs):

• 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.

Icon Component

Note: Here are the results for the "Pega Digital" code base searches (ignore the Pega Core Theme results).

In the Drupal code base and database perform the following tasks.

• Search through the repository for any instances of the @bolt/components-icon component and replace with the @bolt/elements-icon element.

• Double check the "name" prop value to make sure it was not retired. For example, if there was a Icon Component with the following setting.

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

When updating to the Icon Element the "name" value changes to the following:

{% 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.

• 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 backgrounds. The following is an example of the existing props pattern with the Icon Component.

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

The new method of wrapping an icon in a background shape is to do the following:

{% 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.

• We can remove the aria-hidden attribute from the icons since it is hard-coded now. If you see the following example, remove the attributes:{ 'aria-hidden': 'true' }.

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

• If you find a example of a Icon Component web component being used (not the twig version) please replace with the HTML version. The HTML version would require you finding the icon's <path> and paste it within the <svg>. 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 with its HTML version

Web Component Example

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

HTML 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.

• Icon paragraphs - @TODO
  • 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.

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 code base 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 code base 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: Here is the results for the "Pega Digital" code base searches (ignore the Pega Core Theme results).

In the Drupal code base 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, CSS Vars reference can be found here. 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).