Version 8 to 9
This migration guide contains migration instructions for:
- eightshift/boilerplate - 8+ --> 9.0.0
- eightshift/frontend-libs - 7+ --> 8.0.0
- eightshift/libs - 6.4.0
Required changes
Migration time: ~45min to a couple of hours, depending on project size and components used.
- Update
composer
packages and check if Eightshift Libs are on version 6.4 (or higher) - Update
@eightshift/frontend-libs
in yourpackage.json
file to the latest version:"@eightshift/frontend-libs": "^8.0.0",
- Important: Delete your lockfile (
package.lock
) and yournode_modules
folder, then runnpm install
- Rename updated components, update changed properties and replace deprecated components (see chapter below)
- Do a
npm start
, check that you have no build errors visible - Smoke test your blocks - to verify everything was migrated properly, go through all the blocks and check if everything looks good visually and that everything is functional
Component updates and replacements
Below you will find some of the more common components that will need to be modified, and also some possible caveats.
Your code editor should mark the components that need replacement with a strikethrough over the component name:
Common between components
- if you have a label with an
IconLabel
inside, you can migrate it to separateicon
andlabel
props:becomeslabel={<IconLabel icon={icons.color} label={__('Background', 'domain')} />}
icon={icons.color}
label={__('Background', 'domain')} - if the component is the last in the list of options, you can add
noBottomSpacing
to make everything look a bit nicer - if you want to visually group two similar components, e.g. toggles, you can bring them vertically closer together with
reducedBottomSpacing
CollapsableComponentUseToggle
- rename the component and imports to
UseToggle
- change
showUseToggle
tonoUseToggle
and flip its logic - change
showLabel
tonoLabel
and flip its logic - change
showExpanderButton
tonoExpandButton
and flip its logic - consider adding
noExpandButton
to your attributes and add it to all your blocks, so the options render nicely
ComponentUseToggle
- replace the component with
UseToggle
- move all of the options inside the useToggle
- change
showUseToggle
tonoUseToggle
and flip its logic - change
showLabel
tonoLabel
and flip its logic
Example
Before
<ComponentUseToggle
label={label}
checked={accordionUse}
onChange={(value) => setAttributes({ [getAttrKey('accordionUse', attributes, manifest)]: value })}
showUseToggle={showAccordionUse}
showLabel={showLabel}
/>
{accordionUse &&
// Other options.
}
After:
<UseToggle
label={label}
checked={accordionUse}
onChange={(value) => setAttributes({ [getAttrKey('accordionUse', attributes, manifest)]: value })}
noUseToggle={!showAccordionUse} // Inverted logic!
noLabel={!showLabel} // Inverted logic!
noBottomSpacing // If the component is the only one in the options panel
>
// Other options.
</UseToggle>
ColorPaletteCustom
- rename the component and imports to
ColorPalette
- remove the
inline
prop if you have it added - change the
layout
prop to a string instead of aColorPaletteCustomLayout
object (hint: use autocomplete to see all the possible values) - if you have it set, change
groupShades={false}
tonoShadeGrouping
ColorPickerComponent
- rename the component and imports to
ColorPicker
- change the
type
prop to a string instead of aColorPickerType
object (hint: use autocomplete to see all the possible values) - if you have it set, change
groupShades={false}
tonoShadeGrouping
- if you have it set, replace
includeWpBottomSpacing={false}
withnoBottomSpacing
Responsive
- check and remove all breakpoint labels you had set manually, they're now automatically rendered by the component
CompactResponsive
- rename the component and imports to
Responsive
- check and remove all breakpoint labels you had set manually, they're now automatically rendered by the component
CustomSelect
- this component has been split up into 4 more specific components
- if you had a CustomSelect without
multiple
and withoptions
, replace it withSelect
- if you had a CustomSelect without
multiple
and withloadOptions
, replace it withMultiSelect
- if you had a CustomSelect with
multiple
and withoptions
, replace it withMultiSelect
- if you had a CustomSelect with
multiple
and withloadOptions
, replace it withAsyncMultiSelect
- if you had a CustomSelect without
- replace
isClearable
withclearable
if you had it set totrue
- replace
isSearchable
withnoSearch
if you had it set tofalse
, otherwise remove it - remove
reFetchOnSearch
, as it was removed - remove
multiple
(make sure you add the proper kind of Select!) - if you had an async select (with
loadOptions
), and hadsimpleValue
set, you will need to find a slightly different solution, as this is not supported anymore
LinkEditComponent
- ⚠️ props have changed here, it'll leave URL pickers broken if you forget to change them!
- replace
setAttributes
,urlAttrName
,isNewTabAttrName
(if set) with anonChange
callback (see example below) - remove
title
withlabel
if you want to keep it customized (you can also just remove it) - replace
showNewTabOption
withhideOpensInNewTab
and invert its logic - you can now hide the anchor notice with
hideAnchorNotice
Example
Before
url={buttonUrl}
<LinkEditComponent
url={buttonUrl}
opensInNewTab={buttonIsNewTab}
setAttributes={setAttributes}
title={variableLabel}
urlAttrName={getAttrKey('buttonUrl', attributes, manifest)}
isNewTabAttrName={getAttrKey('buttonIsNewTab', attributes, manifest)}
showNewTabOption={showButtonIsNewTab}
/>
After
<LinkEditComponent
url={buttonUrl}
opensInNewTab={buttonIsNewTab}
hideOpensInNewTab={!showButtonIsNewTab} // Inverted logic!
onChange={({ url, newTab, isAnchor }) => setAttributes({
[getAttrKey('buttonUrl', attributes, manifest)]: url,
[getAttrKey('buttonIsNewTab', attributes, manifest)]: newTab,
[getAttrKey('buttonIsAnchor', attributes, manifest)]: isAnchor ?? false, // Optional, can replace a manual toggle (detects setting anchor links automatically).
})}
/>
SimpleVerticalSingleSelect
- replace the component with
OptionSelector
- replace the
options
prop (one that returns an object) withvalue
,onChange
callback and availableoptions
(array)
Example
Make sure your options have at least a label
and a value
!
Before
const sizeOptions = getOption('buttonSize', attributes, manifest).map(({ label, value, icon: iconName }) => {
return {
onClick: () => setAttributes({
[getAttrKey('buttonSize', attributes, manifest)]: value,
[getAttrKey('buttonIsLink', attributes, manifest)]: false
}),
label: label,
isActive: buttonSize === value,
icon: icons[iconName],
};
});
// ...
<SimpleVerticalSingleSelect
label={<IconLabel icon={icons.size} label={__('Size', 'domain')} />}
options={sizeOptions}
/>
After
<OptionSelector
icon={icons.size}
label={__('Size', 'domain')}
options={getOption('buttonSize', attributes, manifest)}
value={buttonSize}
onChange={(value) => setAttributes({
[getAttrKey('buttonSize', attributes, manifest)]: value,
[getAttrKey('buttonIsLink', attributes, manifest)]: false
})}
/>