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.1.1
• fin composer require pega/pega_bolt_theme:8.x-5.x-dev
• fin composer update pega/pega_cd

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

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

Then 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

Note: it is important to run fin fe-build at least once, as this will run the makefiles that install the new version of Node.

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 "module_load_include('install', 'pega_bolt_icon', 'pega_bolt_icon'); _pega_bolt_update_icon_paragraph();"
fin drush cex -y

Commit the exported configuration. IMPORTANT: This function may remove UUIDs in the exported configuration. You should manually unstage any changes to the UUIDs before committing.

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. 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 a example of a pure Icon web component, i.e. <bolt-icon> in plain HTML, please replace with the HTML version of the Icon element. 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:

Icon Web Component example

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

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