Version 6 to 7

This migration guide is represents migration for:

• eightshift/boilerplate - 6+ --> 7.0.0
• eightshift/frontend-libs - 5+ --> 6.0.0
• eightshift/libs - 4+ --> 5.0.0

Required changes

Migration time: ~30min.

1. Make sure that all editor scripts are loaded from @eightshift/frontend-libs/scripts;

2. Make sure that all frontend JS scripts that use frontend helper load ony from @eightshift/frontend-libs/scripts/helpers.

3. We have removed PHP class LabelGenerator and added it in the helper Traits so it you are using it in you project you should refactor it like in the example provided here.

4. In src>Blocks>Blocks.php remove getBlocksPath method because we are not using it anymore.

5. In src>Blocks>Blocks.php replace all instances of $this->getSettings()['namespace'] with Components::getSettingsNamespace(). Generally every place that you use $this->getSettings() use Component store instead.

6. In src>Blocks>Blocks.php add new filter \add_action('wp_footer', [$this, 'outputCssVariablesInline']); to be able to output one style tag styles.

7. In src>Blocks>manifest.json add config keys used to trigger different behaviour of the boilerplate.

   "config": {
   	"outputCssGlobally": true,
   	"outputCssOptimize": true,
   	"outputCssSelectorName": "esCssVariables",
   	"outputCssGloballyAdditionalStyles": [
   		":root {--es-loaded-opacity: 1;}"
   	],
   	"useWrapper": true
   },

8. Open src>Blocks>assets folder and compare it with our new layout and files located here.

9. In src>Enqueue>Blocks>EnqueueBlocks.php add a new action to output new frontend-only styles:

   \add_action('wp_enqueue_scripts', [$this, 'enqueueBlockFrontendStyle'], 50);

10. In src>Enqueue>Blocks>EnqueueBlocks.php rename filter callback enqueueBlockScript to enqueueBlockFrontendScript.

11. Find all usage of ServerSideRender component in JS part. Then in PHP part wherever you use render method you must pass a new attribute blockSsr. Here is an example:

    $featuredContentServerSideRender = Components::checkAttr('featuredContentServerSideRender', $attributes, $manifest);
    
    echo Components::render(
    	'card-article',
    	Components::props(
    		'cardArticle',
    		$props,
    		[
    			'blockSsr' => $featuredContentServerSideRender,
    		]
    	),
    );
    
    echo Components::render(
    	'layout',
    	Components::props('layout', $attributes, [
    		'blockClass' => $blockClass,
    		'blockSsr' => $featuredContentServerSideRender,
    	]),
    );

Improvement changes:

You should replace all instances where you are getting the data directly from the array like $globalManifest['globalVariables'], this can be replaced with Components::getSettings(). Or for examle getting the breakpoints $globalManifest['globalVariables']['breakpoints'] can be replaced with Components::setSettingsGlobalVariablesBreakpoints().

Here are all the links for all of the Store helpers that you can use in PHP and in JS.

PHP example:

$globalManifest = Components::getManifest(dirname(__DIR__, 2));

echo $globalManifest['namespace'];

// replace with

echo Components::getSettingsNamespace();

JS example:

import { globalManifest } from '../../manifest.json';

const {
	namespace,
} = globalManifest;

// replace with
import { select } from '@wordpress/data';
import { STORE_NAME } from '@eightshift/frontend-libs/scripts';

const namespace = select(STORE_NAME).getSettingsNamespace();

Optional changes:

Migration time: ~5min.

1. Find all outputCssVariables function usage (JS and PHP) and remove 4th parameter globalManifest because it is not in use anymore.

Caution

At this point this parameter will not cause any error but it will be removed in the next major release and then it will cause a fatal error so you should remove it.

1. Find outputCssVariablesGlobal function usage (JS and PHP) and remove the parameter globalManifest because it is not in use anymore.

Caution

At this point this parameter will not cause any error but it will be removed in the next major release and then it will cause a fatal error so you should remove it.

1. Add style changes to src>assets>styles>parts>utils>_core.scss file in the body selector to provide content flickering on render. Here is an example:

body {
	//...
	opacity: var(--es-loaded-opacity, 0);

	transition: {
		property: opacity;
		duration: 0.5s;
		delay: 0.6s;
	};
}