UI Upgrade Helper tools

The UI Upgrade Helper consists of a suite of tools. After the tools run, all modified files are listed and displayed in a diff view so you can keep or discard the changes. You can then manually apply the changes to your v8 environment.

You can run all of the tools sequentially with a single command.

CSS Rules Tool

Scans customer stylesheets and updates the CSS selectors to match the changes made when moving to the Carbon Design System.

Iterates over customer CSS files and applies the rules codified in packages/css-rules-tool/rules/*.json.

Example CSS rules file

In this example, all the values in SelectorRemove are deleted. The values in SelectorReplace are replaced by newValue.

    {
      "SelectorRemove": [
        { "value": ".delete-this-selector" },
        { "value": ".delete-this-selector .and-this" }
        { "value": ".delete-this-selector .and-this-as-well" }
      ],
      "SelectorReplace": [
        {
          "value": ".foo .qux",

Ordering of rules

The following steps determine the order of the rules:

All OOTB rules are loaded.
The rules are sorted by length, with the longest items first, inside each of their respective categories SelectorRemove and SelectorReplace.
The SelectorRemove rules are applied first, followed by the SelectorReplace rules.

Icon Replacer Tool

Scans customer source files for V7 icons that were replaced by V8 equivalents.

Iterates over customer source files and replaces the icons codified in packages/icon-replacer-tool/icons_mappings.json.

Example icons mappings ("v7_FILENAME":"V8_FILENAME"):

    {
      "Actions_Blue30_20px.png": "overflow-menu-horizontal--20-on-dark.svg",
      "Actions_Blue50_20px.png": "overflow-menu-horizontal--20-enabled.svg",
      "Calendar_Blue50_20px.png": "calendar--20-enabled.svg",
      "Day_Blue50_20px.png": "calendar__day--20-enabled.svg",
      "Gotodate_Blue50_20px.png": "calendar__go-to-date--20-enabled.svg",
    }

Example V8 icon files:


    `/source_files/overflow-menu-horizontal--20-on-dark.svg`

All V7 icon files that are found are deleted and their V8 equivalents are copied to the same location.

References to the icon in customer source files, such as .css, .js, jspx, are also updated.

Window Size Tool

The Window Size Tool scans UIM files and applies rules to change modals to an appropriate size, based on their content. Where appropriate, UIM files are modified to resize modals to one of five sizes. The IBM Social Program Management Modal component in v8.0.1 has five sizes, the four standard Carbon modal sizes, ‘extra-small’, ‘small’, ‘medium’, and ‘large’, and a custom ‘extra-large’ size. All modified files are listed and displayed in a diff view that shows the previous width value and the new width value. You can keep or discard the changes.

The Window Size Tool ignores UIM files that contain certain types of content:

Wizards.
An include of another UIM or VIM file.
Optionally, fields that render domains that are not specified in a provided allow list.

The domain allow list

Some content needs to be displayed on a larger modal and must not be resized. You can use a provided allow list to help you to filter out files that must not be resized. If you set the containsAllowedDomainsOnly parameter in a rule, the modal size is only reduced if all of the domains that are rendered in a UIM page are in the allow list.

The allow list contains the following field domains:

Domain	Description
CODETABLE_CODE	Maps to a dropdown.
INTERNAL_ID	Maps to an integer.
SHORT_CODETABLE_CODE	Maps to a radio button.
SVR_BOOLEAN	Maps to a checkbox.
SVR_CHAR	Maps to a single character value.
SVR_DATE	Maps to a date input.
SVR_DATETIME	Maps to a date time input.
SVR_STRING	Maps to strings with a length of less than 300, to accommodate names, labels and comments.
SVR_DOUBLE	Maps to a floating point number that corresponds to the Java:tm: primitive data type `double`.
SVR_FLOAT	Maps to a floating point number that corresponds to the Java:tm: primitive data type `float`.
SVR_INT8, SVR_INT16, SVR_INT32, SVR_INT64	Maps to an integer.
SVR_MONEY	Maps to a money value.

Window sizing rules

The window sizing rules define the criteria that are used to identify UIMs to resize. Where the rules are matched based on the width and content of a modal, a new size is set.

The order of the rules is important, as the first rule that matches is applied to each UIM file.
The rules for modal width and content are codified in packages/window-size-tool/rules.json.

Example rules

This rule finds UIM files that contain modals with a width of 576px or lower (x-small or small modals), and contain either a two-column cluster or a four-column list, and changes the size to medium (700 in the code).

  {
    "width": "<= 576",
    "anyTerms": [
      "//CLUSTER/@NUM_COLS = 2", 
      "count(//LIST[count(FIELD | CONTAINER) = 4]) > 0"
    ],
   "allTerms": [
      "count(//INCLUDE) = 0",
      "count(//MENU[@MODE='WIZARD_PROGRESS_BAR']) = 0"

This rule rule finds UIM files that contains modals with a width between 576 and 769 pixels (‘medium’ sized modals) and doesn’t contain any clusters with more than one column, lists with more than two columns, includes of other files, and isn’t part of a wizard. In addition, all domains that are rendered by this UIM file must be on the domain allow list to allow this file be modified.

  {
    "width": "> 576 and <= 768",
    "anyTerms": [],
    "allTerms": [
      "count(//CLUSTER[@NUM_COLS > 1 ]) = 0",
      "count(//LIST[count(FIELD | CONTAINER) > 2]) = 0",
      "count(//CLUSTER) > 0 or count(//LIST) > 0",
      "count(//INCLUDE) = 0",
      "count(//MENU[@MODE='WIZARD_PROGRESS_BAR']) = 0"

Where:

The width parameter is the modal width in pixels. This value is compared to the WINDOW_OPTIONS attribute of any <PAGE> or <LINK> elements that are found.
The anyTerms array defines XPath expressions that are run against each UIM file that matches the width expression. If any of the expressions are true, and all other rule criteria are met, the size of the UIM file is updated.
The allTerms array defines XPath expressions that are run against each UIM file that matches the width expression. If all of the expressions are true, and all other rule criteria is met, the size of that UIM file is updated.
The containsAllowedDomainsOnly parameter is set to true, so all domains that are rendered in the file must be on the allow list. The default value is false.
The target parameter is the new modal size: xs for extra-small, sm for small, md for medium/default, lg for large and xlg for extra-large.

After Window Size Tool runs, the changes that you see are pixel values, such as 700, rather than a size name, such as sm. As WINDOW_OPTIONS in UIM are expressed as pixels, each target size is translated to a pixel width value that is used to set the WINDOW_OPTIONS attribute, see packages/window-size-tool/sizes.js. The UIM rendering framework maps the pixel value of WINDOW_OPTIONS to a Carbon modal size when rendering. For more information about the mappings from WINDOW_OPTIONS to Carbon modal sizes, see PAGE element.

Reviewing Window Size Tool changes

All modified files are listed and displayed in a diff view that shows the previous width value and the new width value. You can keep or discard the proposed changes or make your own changes.

WINDOW_OPTIONS in UIM are expressed as pixels so changes are made to the WINDOW_OPTIONS width in pixels, such as 700, rather than a size, such as sm. Each target size in a rule is translated to an equivalent pixel width value that is used to set the WINDOW_OPTIONS attribute, see packages/window-size-tool/sizes.js.

When a UIM file is rendered, the pixel value of WINDOW_OPTIONS maps to the appropriate Carbon modal size. For more information about the mappings, see the PAGE element. For example, if a modal previously had a width of 550 (between 421 and 576), it was “Small”. If the new modal size is 700 (between 577 and 768), it is now “Medium”.

Example UIM file modification

This example page originally had a width of 550, which according to the WINDOW_OPTIONS to Carbon modal sizes mappings, renders as a small sized modal. However, as the page contains a two-column cluster, according to the rules the size increases to 700 and it renders as a medium sized modal. You can accept the change, reject it or choose a different size.

- <PAGE PAGE_ID="myExamplePage" WINDOW_OPTIONS="width=550">
+ <PAGE PAGE_ID="myExamplePage" WINDOW_OPTIONS="width=700">
  <CLUSTER NUM_COLS="2">
    <FIELD>
      …
    </FIELD>
    <FIELD>
      …
    </FIELD>

When reviewing a modified file, looking up its page preview in IBM Cúram Analysis Documentation Generator (CADG) can give you a quick visual of the layout of the existing page and whether the new size is appropriate. For example, if you see in the page preview that the modal contains a six column list and the width of the modal was updated to 1000 (large), then you can reason that the rules were applied as expected and the new size is appropriate. Note that while CADG page previews are not displayed with SPM v8 styling, (for example, v8 labels are always displayed above input fields), they still provide a useful visual of the structure and contents of a page.

LINK Elements

Not all UIM files that are modified by the tool have WINDOW_OPTIONS on the PAGE element. Typically, these UIM files contain one or more LINK elements, which can open a linked page as a modal by specifying WINDOW_OPTIONS on the LINK element.

The Window Size Tool evaluates the contents of the linked file. If a rule matches, then the WINDOW_OPTIONS on the LINK element are updated, and the UIM file that contains the LINK is modified.

Example UIM file modification based on the content of a linked file

// myRegularPage.uim
<PAGE PAGE_ID="myRegularPage">
-  <LINK PAGE_ID="myModalPage" WINDOW_OPTIONS="width=550">
+  <LINK PAGE_ID="myModalPage"WINDOW_OPTIONS="width=700">
    …
  </LINK>
</PAGE>

// myModalPage.uim
<PAGE PAGE_ID="myModalPage">
  <CLUSTER NUM_COLS="2">
    <FIELD>
      …
    </FIELD>
    <FIELD>
      …
    </FIELD>

Overview

Setting up: Setting up