A simple use case of post templates can be a review or a testimonial. For example, if you want each review to be a separate post and to use a single Quote block.

If you don’t have the new post type registered, you can refer to one of the previous blog posts which explains how to register Custom Post Types. Once the new post type is registered, you can set the template_lock argument.

Template locking options​

The best way to lock the template is by adding the template_lock argument into a return statement from the getPostTypeArguments method in your post type class.

return [
	// ...
	'template_lock' => 'all',
];

There are a few ways of locking the template:

• all - blocks can’t be inserted, removed, or moved around. Content can be edited for existing blocks
• insert - you can’t insert or remove blocks, but you can move them around

Additionally, you can lock each block separately by adding the following attributes:

"lock": {
	"remove": true,
	"move": true,
}

Adding a template​

A recommended approach for adding a post template is to add a service class. For this example, the post type is Review, so the WP-CLI command for creating a new service class looks like this:

wp boilerplate create service-example --folder=Templates --file_name=ReviewTemplate

If you’re adding a template for another post type, create a separate class, but include it in the same namespace (folder). That way you’ll have a much better overview of the templates in the project.

Here’s an example of how to add a single Quote block as a template:

/**
 * Register Review Template.
 *
 * @return void
 */
public function registerReviewTemplate(): void
{
	$reviewPostType = \get_post_type_object(ReviewPostType::POST_TYPE_SLUG);

	$reviewPostType->template = [
		[
			'eightshift-boilerplate/quote',
			[
				'wrapperSimple' => true,
				'quoteQuoteParagraphContent' => 'Content placeholder',
				'quoteQuoteAuthorContent' => 'Author name placeholder',
			]
		],
	];
}

To assign a post template, you need to get the post type object and then update the template property. Alternatively, you can also lock the post template in this method with the template_lock property, but it’s much cleaner to do it during custom post type registration.

Don’t forget to register your method with add_action:

\add_action('init', [$this, 'registerReviewTemplate'], 20);

Building complex layouts​

As you can see from the previous example, you can set any attribute you want, including wrapper-related options. The easiest way to add a complex post template is by building it in the Gutenberg editor first, then switching to Code Editor and copying the content. This will have to be rewritten in PHP to make it work, and here’s how to do it. Let’s say the code for the blocks looks like this:

<!-- wp:eightshift-boilerplate/paragraph {"paragraphParagraphContent":"Placeholder text"} /-->

<!-- wp:eightshift-boilerplate/cta-modal {"ctaModalButtonContent":"Apply now!","ctaModalEndDateHide":true} -->
<!-- wp:eightshift-boilerplate/heading {"wrapperUseShowControl":false,"wrapperSimpleShowControl":false,"wrapperSimple":true,"wrapperAnchorId":"apply-now","headingHeadingContent":"Application form","headingHeadingSize":"h4:bold","headingAlign":"center"} /-->

<!-- wp:eightshift-forms/forms /-->
<!-- /wp:eightshift-boilerplate/cta-modal -->

This is how it looks when you rewrite it in PHP.

$eventPostType->template = [ // array that holds all blocks.
	[ // array that holds a Paragraph block.
		'eightshift-boilerplate/paragraph', // full block name.
		[ // array that holds block attributes.
			'paragraphParagraphContent' => 'Placeholder text',
		]
	],
	[ // array that holds a CTA Modal block.
		'eightshift-boilerplate/cta-modal',
		[ // array that holds block attributes.
			'ctaModalEndDateHide' => true,
			'ctaModalButtonContent' => 'Apply now!',
			'ctaModalButtonAlign' => 'center',
		],
		[ // array of inner blocks for a CTA Modal block.
			[
				'eightshift-boilerplate/heading',
				[
					'wrapperAnchorId' => 'apply-now',
					'headingHeadingContent' => 'Application form',
					'headingHeadingSize' => 'h4:bold',
					'headingAlign' => 'center'
				]
			],
			[
				'eightshift-forms/forms',
				[] // not passing any attributes, so we just include an empty array.
			]
		]
	]
];

The comments were added above for an easier understanding of the structure. So, to summarize:

• the template property is an array that holds all blocks
• each block is a separate array that accepts three values in the following order: block name (string), block attributes (array), and inner blocks (array)
• the process of adding inner blocks is the same as for adding blocks to the main content

Editor options for unlocking the templates​

Even though the templates can be locked, some blocks can still be unlocked. This can be done by selecting a block and clicking on a lock icon. When locking or unlocking a block in this way, you can toggle two options, the ones already mentioned at the end of the Template locking options section:

• Disable movement - disable moving the block around
• Prevent removal - prevents the block from being deleted

That way, even if you lock the template, some modifications can still be made to the template. Please note, that once you remove a block from the locked template, you can’t add it again because the button for adding blocks is disabled.

Suggestions for using post templates​

Post templates offer a great way to streamline the process of adding content for specific post types and making the look and feel of the same post types more uniform. There are lots of ways to use them, so here are some suggestions to give you ideas:

Posts/news articles - a news article needs a title, an image, author information, and some content.

Events - you can put the important information at the top with a few accordions, then follow up with some content and add a CTA button at the bottom that opens a modal with an application form.

Reviews - use a single quote block for displaying user reviews. To make it work with the Featured Content block, you can modify the Featured Content block to render the Reviews CPT content directly, instead of rendering cards.

Why use inner blocks?​

Use of inner blocks allows for more flexibility when building content. Let’s say you’re building a simple two-column layout with image on one side and content on the other side. You can define the components that will be used (e.g. header, paragraph, list, button) and then just toggle the ones you don’t need.

This approach works perfectly fine when you have a strict layout and don’t need larger content structure variations. Using inner blocks may introduce a bit more complexity - both for developers and content editors, but ultimately gives the editors much more freedom.

Another example where inner blocks are used is the Carousel block. Using inner blocks allows you to add as many slides as you'd like in your carousel. Let’s not forget about Columns and Group blocks. These also use inner blocks.

Adding inner block support​

The example used in this blog post is a two-column Card that was made for a project. First thing that needs to be updated is the manifest.json file. For the sake of simplicity and not having too much code, the parts that aren’t related to the inner blocks have been removed.

{
	"hasInnerBlocks": true,
	"innerBlocksDependency": [
		"heading",
		"paragraph"
	],
	"attributes": {
		"cardTwoColumnAllowedBlocks": {
			"type": "array",
			"items": {
				"type": "string"
			},
			"default": [
				"eightshift-boilerplate/paragraph",
				"eightshift-boilerplate/heading",
				"eightshift-boilerplate/button",
				"eightshift-boilerplate/lists"
			]
		}
	}
}

The hasInnerBlocks key defines that this block supports inner blocks. The innerBlocksDependency is generally used to output block dependencies when adding a block via CLI, but it can also be used to add inner blocks automatically. You can see an example of using it in the Columns block editor.js file.

In case we need to limit which blocks can be added inside inner blocks, we can do so with an attribute. Usually, the attribute is named {blockName}AllowedBlocks. Set the default value as an array of strings that represent block names you want to allow.

Please note that the block names must include the block namespace! (eightshift-boilerplate by default, check in Global manifest)

Now you need to pass the allowed blocks attribute into the InnerBlocks component In the {block-name}-editor.js file. Here’s an example of the code related only to the inner blocks:

import { InnerBlocks } from '@wordpress/block-editor';
import { BlockInserter } from '@eightshift/frontend-libs/scripts';

export const CardTwoColumnEditor = ({ attributes, setAttributes, clientId }) => {

	const {
		cardTwoColumnAllowedBlocks,
	} = attributes;

	return (
		<div className={contentClass}>
			<InnerBlocks
				allowedBlocks={(typeof cardTwoColumnAllowedBlocks === 'undefined') || cardTwoColumnAllowedBlocks}
				orientation='vertical'
				renderAppender={() => <BlockInserter clientId={clientId} />}
			/>
		</div>
	);
};

The InnerBlocks component comes from Gutenberg. In order to limit the allowed blocks, we need to pass the list of allowed inner blocks to the allowedBlocks attribute. If your inner blocks should be laid out horizontally in the editor, instead of vertically, you can pass orientation='horizontal'.

renderAppender prop allows passing a custom block insert button. Due to relatively frequent changes in Gutenberg, a custom BlockInserter element is available in Frontend libs as a replacement, and can be passed to InnerBlocks.

Finally, to render the inner blocks in PHP, you need to add the following:

<?php
// phpcs:ignore Eightshift.Security.ComponentsEscape.OutputNotEscaped
echo $innerBlockContent;
?>

And that’s it! Your block now supports inner blocks.

Overriding inner block attributes​

Inner blocks behave like regular blocks, which means they also have a wrapper by default. This may not always be desired and manually removing wrapper or adding custom wrapper settings on each inner block can be tedious. That’s why Eightshift DevKit offers few helpers that allow you to override inner block attributes.

Both of these helpers go to your {block-name}-block.js file.

overrideInnerBlockAttributes​

This helper allows you to set the attributes on all inner blocks by passing them as a third parameter. The example below shows how to disable the wrapper and hide wrapper controls.

import { useSelect } from '@wordpress/data';
import { overrideInnerBlockAttributes } from '@eightshift/frontend-libs/scripts';

export const Accordion = (props) => {
	// Set these attributes to all inner blocks once inserted in DOM.
	useSelect((select) => {
		overrideInnerBlockAttributes(
			select,
			props.clientId,
			{
				wrapperUse: false,
				wrapperNoControls: true,
			},
		);
	});

	return (
		// ...
	);
};

Keep in mind this helper allows you to set any attribute that the inner block supports, so you can even set a larger paragraph size and a different color, for example.

useBlockProps and useInnerBlocksProps​

In case the default InnerBlocks limits your styling and/or layout options too much, you can opt into the newer block prop hooks to implement inner blocks as well!

Import the useBlockProps and useInnerBlocksProps hooks, configure them just like regular InnerBlocks, and spread the params into an element of your choice (div is recommended).

In code, it looks something like this:

import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor';

export const DemoEditor = (props) => {
	const blockProps = useBlockProps();
	const innerBlocksProps = useInnerBlocksProps(blockProps, {
		allowedBlocks: demoAllowedBlocks,
		renderAppender: () => <BlockInserter clientId={clientId} />,
	});

	return (
		<div {...innerBlocksProps} /> // Do whatever you want with this.
	);
};

Conclusion​

The best way to understand how inner blocks work is to try to build your own block that supports inner blocks and try out various options and see what kind of results you’ll get. If you ever get stuck, you can refer to the official Eightshift DevKit documentation or check the blocks that already have inner blocks support. These blocks are:

• accordion
• accordion item
• columns
• column
• carousel
• group

Using only Eightshift blocks​

If you want to remove the default Gutenberg blocks and use only Eightshift blocks, it’s as easy as adding the following code in your src/Blocks/Blocks.php file:

// Limits the usage of only custom project blocks.
\add_filter('allowed_block_types_all', [$this, 'getAllBlocksList'], 10, 2);

ModifyAdminAppearance class​

When you have multiple environments (local, staging, production ...), you may accidentally change something on the wrong environment if you mix up your tabs. The ModifyAdminAppearance class changes your WP Admin color scheme depending on the environment type defined with the WP_ENVIRONMENT_TYPE constant. That way it’s much easier to differentiate on which environment you are when you're in WP Admin.

Now when you get a call from the client asking you why the blog post they published isn’t visible on the site, the first question you can ask is: “What color is the admin area?” 😄

To add it into your project, use the following WP-CLI command:

wp boilerplate create modify-admin-appearance

After adding this class to your project, all you have to do is define the proper environment type in the WP_ENVIRONMENT_TYPE constant in wp-config.php.

The supported values are:

• local
• development
• staging
• production

If you want to change any of the colors, you can do so by modifying the values in COLOR_SCHEMES array inside ModifyAdminAppearance class. For the full list of available color schemes, you can navigate to wp-admin/css/colors. The subfolders here represent the color schemes you can use. For example, if you want to change production environment color scheme to coffee, you would do it like this:

/**
 * List of admin color schemes.
 *
 * @var array<string, string>
 */
public const COLOR_SCHEMES = [
	'development' => 'fresh',
	'local' => 'fresh',
	'staging' => 'blue',
	'production' => 'coffee',
];

EscapedView class​

This class can be used to define which tags and attributes are escaped or allowed in your project. To add the class into your project, use the following WP-CLI command:

wp boilerplate create escaped-view

Here’s an example how to define the allowed tags so wp_kses doesn’t remove them:

	/**
	 * Add tags to allowed HTML list.
	 *
	 * @param array<string, array<mixed>> $tags Allowed tags.
	 *
	 * @return array<string, array<mixed>>
	 */
	public function ksesAllowedHtml($tags): array
	{
		$tags['source'] = [
			'src' => [],
			'type' => [],
		];

		$tags['video'] = [
			'muted' => [],
			'src' => [],
			'autoplay' => [],
			// ...
		];

		$tags['div']['data-*'] = true;

		return \array_merge(
			$tags,
			static::SVG,
			static::FORM,
			static::IFRAME
		);
	}

Don’t forget to add this to the register method:

\add_filter('wp_kses_allowed_html', [$this, 'ksesAllowedHtml'], 20, 1);

Media class​

To add the Media class to your project, use the following WP-CLI command:

wp boilerplate create media

You can use the Media class to define new media sizes or allow uploads of the mime types that are not allowed by default.

	/**
	 * Allow additional types for uploads in media.
	 *
	 * @param array<string, string> $mimes Load all mimes types.
	 *
	 * @return array<string, string> Return original and updated.
	 */
	public function enableMimeTypes(array $mimes): array
	{
		$mimes['svg']  = 'image/svg+xml';
		$mimes['zip']  = 'application/zip';
		$mimes['json'] = 'application/json';

		return $mimes;
	}

And register the filter:

\add_filter('upload_mimes', [$this, 'enableMimeTypes']);

This class also supports converting your media into WebP format, but more on that below.

Automatic WebP conversion​

The WebP file format is becoming more and more popular, with its smaller file sizes and better compression, it is a preferred replacement for .jpg and .png formats. Eightshift DevKit supports converting your existing files to WebP format.

If you already have the Media class in your project, you need to run this WP-CLI command:

wp boilerplate create webp-media-column

This command will add a new column in your List view in Media Library that shows if the media is converted to WebP or not.

To enable and convert existing media to WebP, run the following commands:

wp boilerplate run use-webp-media
wp boilerplate run regenerate-media

After running these commands, you’ll have your images converted to WebP. Some formats like svg will not be converted, this is intended.

Please note that the original files will not be deleted and you’ll have to add additional logic to your Image component for replacing the URLs.

Here’s a simple example how to do it:

// Check if webP is used from admin.
$isWebPUsed = Components::isWebPMediaUsed();

// If webP is used override the url for large.
if ($isWebPUsed) {
	$sourceWebPLarge = Components::getWebPMedia($imageUrl['large'], Media::WEBP_ALLOWED_EXT);

	if ($sourceWebPLarge) {
		$imageUrl['large'] = $sourceWebPLarge['src'];
	}
}

Dynamic cookies for WP Rocket​

This is quite useful when you have a GDPR plugin and you have to take the cookie value into consideration when serving the cached version of the site.

To add the GDPR cookie to the list of dynamic cookies, create a new class called Rocket with the following WP-CLI command:

wp boilerplate create service-example --folder=Plugins/Rocket --file_name=Rocket

Add the following method to the Rocket class:

	/**
	 * List all dynamic cookies that will create new cached version.
	 *
	 * @param array<string> $items Items from the admin.
	 *
	 * @return array<string>
	 */
	public function dynamicCookiesList(array $items): array
	{
		$items[] = 'gdpr';

		return $items;
	}

Finally, add the following filter to the register method:

\add_filter('rocket_cache_dynamic_cookies', [$this, 'dynamicCookiesList']);

Yoast SEO helper​

The content generated by Eightshift blocks may be difficult for Yoast SEO to interpret, but there is a Yoast SEO helper included in our DevKit that fixes the issue and makes the content readable to Yoast SEO. By default, Yoast SEO can't read the content from custom dynamic blocks, so this helper tells it how to parse the content from the blocks.

To enable this, you have to add the following in src/Blocks/assets/scripts/application-blocks-editor.js:

import { yoastSeo } from '@eightshift/frontend-libs/scripts/plugins';

// ...

yoastSeo();

Linters and Coding Standards checks​

Eightshift DevKit includes coding standards checks that will help you improve your code quality.

To run these commands, you have to be in the theme root folder. Here’s the list:

• npm run lintStyle - check your CSS files with StyleLint
• npm run lintJs - check your JS files with ESLint
• composer test:standards - check PHP coding standards errors with PHPCS
• composer test:types - runs PHPStan static code analysis

Making strings translatable in PHP​

A good practice is to use one of the I18n (internationalization) functions for your hardcoded strings, even if your website starts with a single language. This way, you can add multilingual support more easily later.

If you've worked on a multilanguage-capable project, you most likely came across __() and _e() functions. The main difference between the __() and _e() is that __() returns the value, while _e() echoes it. Both functions take two arguments: the first one is the string to be translated, and the second one is the textdomain that identifies the translation file.

Textdomain is usually your project name written in kebab-case.

While WordPress functions like __() and _e() will definitely do the job, it is much better to use the variants of these functions that also escape the output. These are esc_html__() and esc_html_e(). There are also a few more functions for I18n you can use, but to keep it simple, we'll just mention these two for now.

Here is an example of using one of these functions:

<?php echo esc_html__('Contact', 'project-name'); ?>

Making strings translatable in JS​

To translate the strings in the Block editor or options, you will first have to import the function from the @wordpress/i18n library.

import { __ } from '@wordpress/i18n';

To output your string, simply use it like this:

{__('Icon position', 'project-name')}

Alternative functions you can use are:

• _n for singular/plural forms
• _nx for singular/plural forms with gettext context
• _x for a translated string with a gettext context

You can refer to the block editor handbook for more information on these functions.

The I18n class​

The easiest way to add I18n support to a project created with Eightshift boilerplate is by using the WP-CLI command:

wp boilerplate create i18n

This command generated a new class inside the src/I18n folder. This class instructs WordPress to look for translations in src/I18n/languages with the textdomain defined as your project name. The next step is generating .po and .mo files that are used for translation.

Generating .pot file​

You can create a .pot (Portable object template) file by using WP-CLI. Run the following command in your project root:

wp i18n make-pot

Alternatively, you can use tools like Poedit to generate a .pot file and generate translations from it later.

Translating with Poedit​

Once you have the .pot file, you can use Poedit to generate .po and .mo files that are used for translating hardcoded strings in your project. When generating the files, you can choose for which locale you're creating the translation for. For example, if you are creating a translation for the German language, your files should be named de_DE.po and de_DE.mo.

After generating the files, go to Translation -> Properties and navigate to the Sources Paths tab. Set the Base path to the theme folder path. In Excluded paths you can add folders like node_modules, vendor, and public to exclude external packages.

In the Sources keywords tab you can set additional functions for use in your project for translations. Commonly used functions are:

• _e for translating a string and echoing it
• __ for returning a translated string
• esc_html__ for returning a translated string which is escaped in a way it's safe to use within HTML
• esc_html_e for echoing a translated string which is escaped in a way it's safe to use within HTML
• esc_attr__ for returning a translated string which is escaped in a way it's safe to use within an attribute
• esc_html_x for returning a translated string which is escaped in a way it's safe to use within HTML, with a gettext context
• _n for returning a translated string in a singular or plural form, based on the supplied number

If you're missing a string in your .po file be sure to check which function is used for translation for that string, and that the function is added to Sources keywords.

After updating the settings, click on Update from source code option to get the updated list of strings to translate.

The translation process is simple. The left column represents the source text, and the right column the translation. When you have finished translating the strings, copy the .po and .mo files to the src/I18n/languages folder.

JS translations​

The process of translating strings in JS has a couple of extra steps.

In order to translate strings in JS (e.g. Block editor strings), you will have to generate translation file. To do this, navigate to your src/I18n/languages folder and use the following WP-CLI command:

wp i18n make-json <po-file> --no-purge

This will generate a .json file for each JS file present. The strings are extracted from .po files, so you'll already have the translations added. The --no-purge flag is used to keep the existing translations in the .po file.

The method used for setting the script translations is setScriptTranslations() from the I18n class.

The default way this works in Eightshift DevKit is that you need to have a single .json file with all the JS translations. If needed, you can either modify this method to read from multiple files, or just merge all the .json files into one.

If using the default setup (everything in one file) follow this naming structure: {textdomain}-{locale}-{handle}.json.

For example, if your textdomain is project-name and your locale is de_DE, your file should be named project-name-de_DE-project-name-block-editor-scripts.json.

The block-related translations depend on the language the user has set in WP admin.

Enabling languages and content translation​

If the website itself needs to support content in multiple languages, a plugin is a good option.

The most common multi-language plugins are:

• WPML - one of the most popular plugins on the market. It is a paid plugin, but offers a lot of advanced options.
• Polylang - a free plugin (also has a paid Pro version).

Explore other options as well, you might find a plugin that is a better fit for your project than WPML or Polylang.

Most of the translation work will be done through the editor, since you'll need to translate the content on posts and pages.

Additional resources​

Internationalization (I18n) and Localization (L10n) are very broad topics, so it's impossible to cover everything in a single blog post.

If you wish to know about the core I18n functionalities, or a bit more about how it is used in the Eightshift DevKit, here are a few resources which you may find interesting:

• WordPress Codex - I18n for WordPress Developers
• Eightshift Development kit documentation - Tips & Tricks
• Infinum WordPress Handbook - Localization

What are WordPress templates?​

Before the days of Full Site Editing in WordPress, we used template files to add custom layouts to a blog page or post archives.

Depending on your setup, you might still use those as they are still a core part of WordPress themes.

Usage in templates​

Thanks to the Components helper, we can easily render() any component in our template.

For this example, we'll use index.php, as you already have it in your theme. If not, use the code below:

<?php

/**
 * Display regular index/home page
 *
 * @package InfinumLibs
 */

use InfinumLibsVendor\EightshiftLibs\Helpers\Components;

get_header();

if (have_posts()) {
	while (have_posts()) {
		the_post();
		the_title();
		the_content();
	}
}

get_footer();

And there it is, a bog-standard blog page that you can style only "the old way"... But not in our case!

Using the Wrapper component​

First, let's import our Components helper class. Make sure to use the namespace from your composer.json.

use InfinumLibsVendor\EightshiftLibs\Helpers\Components;

If we look deeper into the render method, we'll see that for the $component parameter, we can pass the component's name or the full path (ending with .php). We made it simple, so use wrapper.

We have two required properties to add to the Wrappers manifest.json: wrapperOnlyOutput and wrapperManualContent.

"wrapperOnlyOutput": {
	"type": "boolean",
	"default": false
},
"wrapperManualContent": {
	"type": "string",
	"default": ""
}

echo Components::render(
	'wrapper',
	[
		'wrapperOnlyOutput' => true,
		'wrapperManualContent' => '',
	],
	'',
	true
);

Wrapper output​

Now that we have a working Wrapper component in our template, it's time to display posts in the loop.

Let's use the Card from the Frontend Libs as it's the perfect component to display post details and pass it to the wrapperManualContent.

To make the Card component look even better, we'll use some of the powerful properties the Wrapper component has to offer and add spacing between each item.

'wrapperSpacingTopLarge' => 50,
'wrapperSpacingBottomLarge' => 50,

Final result​

<?php

/**
 * Display regular index/home page
 *
 * @package InfinumLibs
 */

use InfinumLibsVendor\EightshiftLibs\Helpers\Components;

get_header();

if (have_posts()) {
	while (have_posts()) {
		the_post();

		echo Components::render(
			'wrapper.php',
			[
				'wrapperOnlyOutput' => true,
				'wrapperManualContent' => Components::render('card', [
					'introContent' => sprintf(__('On %1$s by %2$s', 'eightshift'), get_the_date(), get_the_author_meta('display_name')),
					'headingContent' => get_the_title(),
					'paragraphContent' => apply_filters('the_content', get_the_excerpt()),
					'buttonContent' => __('View more', 'eightshift'),
					'buttonUrl' => get_permalink(),
				]),
				'wrapperSpacingTopLarge' => 50,
				'wrapperSpacingBottomLarge' => 50,
			],
			'',
			true
		);
	}
}

get_footer();

Conclusion​

Although the Wrapper is (usually) not intended to be used as a standalone component, there is a nice benefit to having a time-saving, out-of-the-box solution for displaying content in a grid already defined in your project.

Usage in built-in blocks​

One of the Eightshift blocks that already uses WP_Query is the Featured Content block. In that block, you can see the query logic is inside the block. However, there is a much better way to do it. The reason it was done like this was to simplify this block and to have an already functioning block available with one WP-CLI command.

A much better approach would be to separate the query logic from the block. Other than following the MVC architecture more closely, this will also make the query logic more reusable. To do this, we’re gonna create a service class.

What are Service classes?​

Put simply, a Service is any PHP object that performs some sort of "global" task. - Symfony docs

If you take a look at the ServiceInterface interface, you’ll notice it only contains the register() method. This method holds action and filter hooks for that class. Other than hooking into existing actions and filters, this method can be used to register our own filters which can be used in blocks or other classes.

Basically, whenever you need to hook into actions or filters, you should use a Service class for that.

Creating a new service class​

Creating a new service class in your project is as simple as using the following WP-CLI command:

wp boilerplate create service-example --folder=CustomQuery --file_name=CustomQuery

Once this new class is generated, you can add a new public method that will contain the query logic. We want our method to accept three optional arguments:

• ID of the category
• number of posts per page
• number of the current page

Having the category ID optional will allow for one more use case, and that is fetching the latest posts regardless of category. By default, WordPress sorts the posts by publish date, from newest to oldest.

/**
 * Get posts by category ID.
 *
 * @param int $categoryId Category ID.
 * @param int $postsPerPage Number of posts per page.
 * @param int $currentPage Current page number.
 *
 * @return WP_Query Query object.
 */
public function getPostsByCategory($categoryId = null, $postsPerPage = 3, $currentPage = 1): WP_Query
{
	$postArgs = [
		'post_type' => 'post',
		'cat' => $categoryId,
		'posts_per_page' => $postsPerPage,
		'paged' => $currentPage,
	];

	return new WP_Query($postArgs);
}

To use this method, we can add it as a filter. The filter name should be added as a constant for easier maintenance. Inside the register() method, add the following:

\add_filter(self::GET_POSTS_BY_CATEGORY, [$this, 'getPostsByCategory'], 10, 3);

Using the new filter​

Here are some examples how you can use the filter:

// Get 3 latest posts, regardless of category.
$allLatestPosts = apply_filters(CustomQuery::GET_POSTS_BY_CATEGORY, null);

// Get 10 latest posts from the News category. News category ID is 2.
$latestNews = apply_filters(CustomQuery::GET_POSTS_BY_CATEGORY, 2, 10);

// Get another page of News category.
$pagedNews = apply_filters(CustomQuery::GET_POSTS_BY_CATEGORY, 2, 10, $currentPage);

The above example shows multiple use cases. The first two examples could be used in a simple block that displays only the selected number of the latest posts. The last example may be used in a REST route for a load more functionality or in a block with classic pagination.

Now you can do a regular query loop in your block to display the posts:

if ($latestNews->have_posts()) {
	while ($latestNews->have_posts()) {
		$latestNews->the_post();
		// render the card here with the Components::render helper.
	}
}
wp_reset_postdata();

Prepare only the data you need​

If you would like to improve this even further, you can run the have_posts() loop inside the class and save only the data you need to render to an array. This makes the logic even more separated from the view and all you have to do in a block is loop through the array and populate the component attributes with the values from the array.

$postData = [];

if ($queryData->have_posts()) {
	while($queryData->have_posts()) {
		$queryData->the_post();

		$postData[] = [
			'id' => get_the_ID(),
			'title' => get_the_title(),
			'url' => get_permalink(),
			'image' => get_the_post_thumbnail_url(),
			'date' => get_the_time('d.m.Y.'),
			'excerpt' => get_the_excerpt(),
		];
	}
}

wp_reset_postdata();

return $postData;

Best practices for queries​

It’s important to have query optimisation in mind. Some queries may be a lot slower and you have to see if there is any way to follow the best practices for database queries.

An example of this use case is the Card component, which uses two heading components. You may get the general idea by just going through the code and trying to reverse-engineer it, but this example will give you a much better understanding of how it works and how to use it. First, let's cover some basics.

Manifest and attributes​

The way multiple same components work is by having a different key. Here is an example of the Card component:

"components": {
	"image": "image",
	"intro": "heading",
	"heading": "heading",
	"paragraph": "paragraph",
	"button": "button"
},

As you can see, one heading component has the intro key, while the other one has the heading key. That way the intro heading component is being referred to as intro so there is no mixup with the attribute values between the two heading blocks. This can be seen when setting the default attributes:

"cardIntroSize": {
	"type": "string",
	"default": "tiny"
},
"cardHeadingSize": {
	"type": "string",
	"default": "big"
}

The "props" Helper​

This method does all the heavy lifting for us. It replaces the default attribute names with the ones we provide. There is both the PHP and JS version of it.

Components::render('heading', Components::props('intro', $attributes, [
	'selectorClass' => 'intro',
	'blockClass' => $componentClass
]))

<HeadingEditor
	{...props('intro', attributes, {
		selectorClass: 'intro',
		blockClass: componentClass,
	})}
/>

If you var_dump the props helper, you’ll notice the prefix key, which is built from the names of the blocks and components used hierarchically. For example, when looking at a regular Heading component in the Card block, the prefix will be:

cardCardHeading - first is the Card block name, then the Card component name and finally Heading component name.

The Heading component that is called Intro then has the prefix cardCardIntro. This prefix is then added to the attribute name, which then finally results in cardCardHeadingSize and cardCardIntroSize attributes, for example.

While at first glance it seems strange to have this naming scheme, it actually allows us to figure out the hierarchy just by looking at the attribute name.

A step-by-step example​

The block we'll be creating as an example will be a block which we can use for some sort of comparison or listing pros and cons. To create it, we will need the following:

• two Heading components
• two List components

The easiest way to create a new block is by using the boilerplate command

wp boilerplate blocks use-block --name=example

Once the new block is added to your project, rename it. Also, don’t forget to update all file names and imports in JS.

We should start with manifest.json, where we define the components we'll use and set the default attributes. For now, just define the components and their keys:

"components": {
	"heading": "heading",
	"lists": "lists",
	"secondaryHeading": "heading",
	"secondaryLists": "lists"
}

The first section has the default key names, while the "duplicates" have different key names.

After manifest, we can move to the JS part. As this is a fairly simple block without any advanced options or layouts, we need to add two HeadingEditor components and two ListsEditor components. To make styling easier, we can separate them in two div elements. When you’re finished, your code should look like this:

import React from 'react';
import { __ } from '@wordpress/i18n';
import { HeadingEditor } from '../../../components/heading/components/heading-editor';
import { ListsEditor } from '../../../components/lists/components/lists-editor';

import { props, selector } from '@eightshift/frontend-libs/scripts';

export const ComparisonEditor = ({ attributes, setAttributes }) => {
	const {
		blockClass,
	} = attributes;

	const comparisonPrimaryClass = selector(blockClass, blockClass, 'primary');

	const comparisonSecondaryClass = selector(blockClass, blockClass, 'secondary');

	return (
		<div className={blockClass}>
			<div className={comparisonPrimaryClass}>
				<HeadingEditor
					{...props('heading', attributes, {
						blockClass: blockClass,
						setAttributes: setAttributes,
					})}
				/>

				<ListsEditor
					{...props('lists', attributes, {
						blockClass: blockClass,
						setAttributes: setAttributes,
					})}
				/>
			</div>
			<div className={comparisonSecondaryClass}>
				<HeadingEditor
					{...props('secondaryHeading', attributes, {
						selectorClass: 'secondary-heading',
						blockClass: blockClass,
						setAttributes: setAttributes,
					})}
				/>

				<ListsEditor
					{...props('secondaryLists', attributes, {
						selectorClass: 'secondary-lists',
						blockClass: blockClass,
						setAttributes: setAttributes,
					})}
				/>
			</div>
		</div>
	);
};

Note how we defined the different names with the props helper. Additionally, we set the selector class for easier targeting of components when styling.

Next, we can add the options. Again, the props helper does all the heavy lifting for us. This is how the code should look after adding all component options:

import React from 'react';
import { __ } from '@wordpress/i18n';
import { props, getOptions } from '@eightshift/frontend-libs/scripts';
import { HeadingOptions } from '../../../components/heading/components/heading-options';
import { ListsOptions } from '../../../components/lists/components/lists-options';
import { PanelBody } from '@wordpress/components';
import manifest from '../manifest.json';

export const ComparisonOptions = ({ attributes, setAttributes }) => {
	return (
		<PanelBody title={__('Comparison', 'eightshift')}>
			<HeadingOptions
				{...props('heading', attributes, {
					setAttributes,
					options: getOptions(attributes, manifest)
				})}
				reducedBottomSpacing
			/>

			<ListsOptions
				{...props('lists', attributes, {
					setAttributes,
					options: getOptions(attributes, manifest)
				})}
				reducedBottomSpacing
			/>

			<HeadingOptions
				{...props('secondaryHeading', attributes, {
					setAttributes,
					options: getOptions(attributes, manifest)
				})}
				label={__('Secondary Heading', 'eightshift')}
				reducedBottomSpacing
			/>

			<ListsOptions
				{...props('secondaryLists', attributes, {
					setAttributes,
					options: getOptions(attributes, manifest)
				})}
				label={__('Secondary Lists', 'eightshift')}
				reducedBottomSpacing
			/>
		</PanelBody>
	);
};

Adding the PHP part should be simple, but here is the code for reference:

<?php

/**
 * Template for the Comparison Block view.
 *
 * @package Eightshift
 */

use EightshiftVendor\EightshiftLibs\Helpers\Components;

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

$blockClass = $attributes['blockClass'] ?? '';

$comparisonPrimaryClass = Components::selector($blockClass, $blockClass, 'primary');

$comparisonSecondaryClass = Components::selector($blockClass, $blockClass, 'secondary');

$unique = Components::getUnique();

?>

<div class="<?php echo esc_attr($blockClass); ?>">
	<?php echo Components::outputCssVariables($attributes, $manifest, $unique, $globalManifest); ?>
	<div class="<?php echo esc_attr($comparisonPrimaryClass); ?>">
		<?php
			echo Components::render('heading', Components::props('heading', $attributes)),
			Components::render('lists', Components::props('lists', $attributes));
		?>
	</div>
	<div class="<?php echo esc_attr($comparisonSecondaryClass); ?>">
		<?php
			echo Components::render('heading', Components::props('secondaryHeading', $attributes)),
			Components::render('lists', Components::props('secondaryLists', $attributes));
		?>
	</div>
</div>

The block should work properly now, but the two lists look the same. To make a difference between the two, we can change the default list colors in the manifest. If we don’t have the colors we want already available in the project, first we need to add them to the global manifest.

For a detailed explanation on how to add new colors to your project, you can read a previous blog post about modifying blocks.

Now we have to add these new colors to the Lists component manifest.json. In options key, find the listsColor and add your new colors.

When the new colors are added to the Lists component, we can set these new colors as defaults by adding the following attributes in manifest.json of our Comparison block:

"comparisonListsColor": {
	"type": "string",
	"default": "green-haze"
},
"comparisonSecondaryListsColor": {
	"type": "string",
	"default": "milano-red"
}

The first list will now have green bullet points, and the second one will have red bullet points.

Notice again how the attribute name is structured - current block name (comparison), component name (Lists or SecondaryLists), attribute (Color).

If you’re ever in doubt of what is the exact attribute name, you can always var_dump the props helper for that component and you will see the full attribute names as the keys.

Array
(
    [prefix] => comparisonSecondaryLists
    // ...
    [comparisonSecondaryListsOrdered] => ul
    [comparisonSecondaryListsSize] => body:regular
    [comparisonSecondaryListsColor] => milano-red
    [comparisonSecondaryListsColorOnlyMarker] =>
    [comparisonSecondaryListsUse] => 1
    // ...
)

Conclusion​

Although this was a simple example, we covered the most important things to have in mind when using multiple same components in a block. For additional practice, you can add some more attributes or go through some of our pre-made blocks which use multiple same components. Some components/blocks you can look into are Card and Quote.

What are Block Patterns and why use them?​

Block Patterns are predefined block layouts which allow you to add content faster and make it look more consistent. The basic idea is to have a ready-made template which consists of multiple blocks, that have options predefined, and all you have to do is add content to these blocks.

They can be used in multiple ways. You can create sections composed of few blocks which you can then easily insert anywhere on the site. You can also create complex page layouts which could be used for writing blog posts, for example.

Technical differences​

As explained in the Eightshift Development kit documentation, the main difference between variations and patterns are:

• variations provide data using manifest.json, while patterns are registered using PHP
• variations appear in the editor in the same tab as blocks, while patterns appear in their own tab

Registering Block Patterns​

To make registering new block patterns easier, there is a WP-CLI command which will help you create a new block pattern. For this example, the block pattern we're making is called Intro. To get started, run this WP-CLI command:

wp boilerplate blocks create-block-pattern --title=intro

After generating the block pattern class, there are a few more adjustments you should make to it. For starters, you should update these methods:

• getName() - change the return value to eightshift-boilerplate/intro-pattern
• getDescription() - add any description you like

Once these values are updated, you can make the layout you'll use as a Block Pattern. The easiest way to do it is to build your layout in the editor, switch to Code Editor, copy the code and paste in inside your getContent() method. Your pattern should now be available to use. For this example, we can create a simple pattern which consists of a Heading block and a Paragraph block.

protected function getContent(): string
{
	return '<!-- wp:eightshift-boilerplate/heading {"headingHeadingContent":"Post title goes here","headingHeadingSize":"big"} /-->
	<!-- wp:eightshift-boilerplate/paragraph {"paragraphParagraphContent":"\u003cem\u003ePost intro goes here\u003c/em\u003e"} /-->';
}

Managing Pattern Categories​

To make managing block patterns easier, we can group them into categories. To start, we need a service class. This class will be used to register our custom categories and remove core categories. The fastest way to add it to our project is by using the following WP-CLI command:

wp boilerplate create service-example --folder=BlockPatterns --file_name=ManagePatternCategories

Now that we have our service class, we'll add methods for removing core patterns and pattern categories. First, the method for removing core categories.

/**
 * Unregisters core block pattern categories.
 *
 * @return void
 */
public function removeCoreCategories()
{
	\unregister_block_pattern_category('buttons');
	\unregister_block_pattern_category('columns');
	\unregister_block_pattern_category('gallery');
	\unregister_block_pattern_category('header');
	\unregister_block_pattern_category('text');
}

The second method will remove all core patterns

/**
 * Removes support for core block patterns.
 *
 * @return void
 */
public function removeBlockPatternsCore()
{
	\remove_theme_support('core-block-patterns');
}

For these methods to work, we need to add them to the register() method of our service class. Add the following actions:

\add_action('init', [$this, 'removeCoreCategories'], 40);
\add_action('after_setup_theme', [$this, 'removeBlockPatternsCore'], 20);

If you try searching for patterns in your editor, you'll notice they are no longer available. Now we can move on to adding our block pattern categories. The best approach is to define the pattern category names as constants inside your class. In this example, we will add two categories: Templates and Sections. We can add the following code inside our class:

class ManagePatternCategories implements ServiceInterface
{
	public const TEMPLATES_CATEGORY = 'templates-category';
	public const SECTIONS_CATEGORY = 'sections-category';

	// Removed parts of code for better readability.

	/**
	 * Registers new pattern categories.
	 *
	 * @return void
	 */
	public function addCategories()
	{
		\register_block_pattern_category(self::TEMPLATES_CATEGORY, [
			'label' =>  \esc_html__('Templates', 'es-blog'),
		]);

		\register_block_pattern_category(self::SECTIONS_CATEGORY, [
			'label' => \esc_html__('Sections', 'es-blog'),
		]);
	}
}

Finally, return to your Intro Pattern class and update the getCategories() method:

protected function getCategories(): array
{
	return [
		ManagePatternCategories::SECTIONS_CATEGORY
	];
}

In editor, in the Pattern tab, you should now see your new pattern category and the Intro Pattern.

Things to keep in mind​

Block patterns add layout and content which you can then modify at will per instance. These instances are not synchronised with the codebase so it becomes an issue if you've already used a pattern on multiple places on the site and then notice you've missed something in the pattern configuration phase. Fixing the pattern in the codebase will apply the changes on all newly added instances, but you will have to fix the misconfigured instances manually.

Why should you use CPTs?​

The great thing about WordPress is how extensible it is. With projects becoming more complex, the need for additional post types and taxonomies increases. Sure, you can cram everything into default posts or pages, but this can become very chaotic. Using custom post types allows you to manage your content much better. You can separate events and projects from news articles for instance.

Post category and tag are taxonomies - a grouping you can further separate by terms belonging to that taxonomy. WordPress, since version 2.3.0 offers a way to register your own, custom taxonomies.

Registering Custom Post Types​

For this exercise, we'll create a new post type called Projects. To make the process of registering new CPTs as easy as possible, we'll use a WP-CLI command to create our CPT with the following command:

wp boilerplate create post-type --label='Project' --plural_label='Projects' --slug='project' --rewrite_url='project' --rest_endpoint_slug='projects'

Your new post type is registered and ready to use! Easy, right?

Sometimes all these parameters can be a bit confusing, so here's a quick reference of best practices when setting these parameters:

There is a reason for this naming convention. For example:

• slug is attached to a single custom post type in the database, which is why it is written in singular
• rest_endpoint_slug is used to fetch a collection of posts from that custom post type, which is why it should be written in plural

Registering Taxonomies​

Now that we have the new custom post type, we need a way to group the projects. We'll create a custom taxonomy called Project Technology. As with the CPT registration, the easiest way to register taxonomies is by using the following WP-CLI command:

wp boilerplate create taxonomy --label='Project Technology' --plural_label='Project Technologies' --slug='project-technology' --rest_endpoint_slug='project-technologies' --post_type_slug='project'

Similar suggestions apply to the parameters when naming taxonomies as well. Be sure to write the correct post type slug for which you are registering this new taxonomy!

Structure​

When checking your codebase after adding these new custom post types and taxonomies, you'll notice the post types are located inside the src/CustomPostType folder, and the taxonomies are located inside the src/CustomTaxonomy folder. Following the Single Responsibility Principle, each post type or taxonomy is in a separate class.

Modifying options​

Our custom post type and taxonomy are ready to use, but we still want to make some changes. For starters, we want another icon and for the Projects to be located below the Posts in the WordPress admin menu. In src/CustomPostType/ProjectPostType.php, find the MENU_POSITION constant and change it to 5. The lower the number, the higher it will be in the menu.

Next, we want to update the icon representing the new post type in the menu. These icons are named dashicons. Change the MENU_ICON constant to dashicons-clipboard. If you want another icon for your CPT, here is the list of available dashicons. Finally, we want to remove the author and comments. In getPostTypeArguments() method, find the key supports in the return value and remove author and comments from the array.

Clashing slugs​

Something that can happen when working on your project is that you have the same slugs for your custom post type and your page, for example. Let's say you have a page with a slug project, and a custom post type with a slug project. When trying to access the page, you'll keep getting the Project CPT archive. To fix it, you have to change one of the slugs or write a custom redirection rule (which we don't recommend, as the redirections are tricky to handle in WordPress).

Further reading​

For the best overview of all the options you have when registering your custom post type or taxonomy, we recommend checking the official WordPress docs for the register_post_type() and register_taxonomy() functions.

If you would like to know more about taxonomies and terms, along with how they are stored in the database, you can read more about it in the Categories, Tags, & Custom Taxonomies page of the WordPress docs.

What are variations?​

Block variations allow us to override default block attributes. We can select a variation from the block list with all preset options instead of manually setting them.

For example, we have a Card block. If we want to use it for something like downloading PDF files, we may not need image or paragraph components. A simple text that describes type of the file, title of the file and a download button are all we need in this case.

Our new card should consist of the following components:

• intro
• heading
• button

How to register a block variation?​

The process of registering block variations is fairly simple. In order to register a block variation, go to src/Blocks/variations, add a new folder, and let's call it card-resource. Inside that folder, all you need to do is add a manifest.json file. It is also recommended to add a docs folder in which you can add a readme file and storybook file.

Inside your manifest.json file, add the attributes to define the new default attributes for this variation. Here is an example:

{
	"$schema": "https://raw.githubusercontent.com/infinum/eightshift-frontend-libs/develop/schemas/variation.json",
	"parentName": "card",
	"name": "card-resource",
	"title": "Card Resource",
	"description" : "Card variation without image and paragraph",
	"icon": {
		"src": "es-card"
	},
	"attributes": {
		"cardCardImageUse": false,
		"cardCardParagraphUse": false,
		"cardCardHeadingSize": "regular",
		"cardCardButtonColor": "blue"
	},
	"scope": [
		"inserter"
	]
}

After adding this code, your new block variation should now be visible in the block list. It's that easy!

Providing inner block data​

Other than overriding default attributes with variations, you can do much more with Eightshift Development kit. If you have a block that uses inner blocks, you can even provide inner block data.

The following example is very basic, but it will give you an idea of how to provide inner block data. It can easily be reproduced with our Carousel block if you want to try it yourself.

Once you have the Carousel block up and running, create a variation called Carousel Loop. For this variation, we want the following:

• loop
• pagination
• two images per slide

We will also add some placeholder images so you can immediately test the Carousel block variation. Here is the code you can add to the manifest.json file for that variation.

{
	"$schema": "https://raw.githubusercontent.com/infinum/eightshift-frontend-libs/develop/schemas/variation.json",
	"parentName": "carousel",
	"name": "carousel-loop",
	"title": "Carousel Loop",
	"description" : "Carousel block variation with loop and pagination enabled, along with multiple image blocks with placeholders. Displays two images per slide.",
	"icon": {
		"src": "es-card"
	},
	"attributes": {
		"carouselIsLoop": true,
		"carouselShowPagination": true,
		"carouselShowItems": 2
	},
	"innerBlocks": [
		{
			"name": "eightshift-boilerplate/image",
			"attributes": {
				"imageImageFull":true,
				"imageImageUrl": "https://loremflickr.com/400/400"
			}
		},
		{
			"name": "eightshift-boilerplate/image",
			"attributes": {
				"imageImageFull":true,
				"imageImageUrl": "https://loremflickr.com/400/400"
			}
		},
		{
			"name": "eightshift-boilerplate/image",
			"attributes": {
				"imageImageFull":true,
				"imageImageUrl": "https://loremflickr.com/400/400"
			}
		},
		{
			"name": "eightshift-boilerplate/image",
			"attributes": {
				"imageImageFull":true,
				"imageImageUrl": "https://loremflickr.com/400/400"
			}
		}
	],
	"scope": [
		"inserter"
	]
}

After adding this code, you should see the Carousel Loop variation in your block list. After adding it in the editor, the Carousel attributes will be already set to the ones you provided, as well as two images that are added as inner blocks.

Ways of registering ACF fields​

There are multiple approaches to ACF field registration. The easiest way to register fields is using the WP admin interface, but this approach has a few drawbacks. If you have many fields, this can impact performance because you are registering fields dynamically (information about registered fields is stored in the database). Another drawback is if you have multiple environments (e.g. local, staging, production), you'll have to export the fields and import them to other environments.

Other ways of registering ACF fields are either via PHP (code) or by reading from a JSON file. We prefer to use PHP because you can use OPcache to speed up field registration even more. If you are using Git, this approach is even better because you can commit the PHP code used for registering fields for easier portability across different environments. For that reason, Eightshift Development kit already has some goodies which will make field registration a breeze.

Exporting PHP code​

The approach we use for registering ACF fields is by adding those fields first through the WP Admin ACF interface. As an example, We'll add a field group called Intro, which will contain one text field of the same name. That field group will be displayed only on posts. You can add a few more fields, but for the sake of simplicity, we'll only use one field.

When you define all the fields you need, save them and go to Custom Fields -> Tools. Here you will see an option to Export Field Groups. Simply select the field groups which you want to export and select Generate PHP.

This will generate a PHP code snippet that you can use in your theme. Now you may be wondering, where exactly should that code go?

CustomMeta class​

Those ACF goodies in Eightshift Development kit we talked about earlier? Let us introduce you to one of them. We have a WP CLI command which we can use to generate a CustomMeta class where we can add our field groups. The command is wp boilerplate create acf-meta. This command has one required parameter, and that is name. To create a class that we will use for registering our custom fields, we'll use the following command:

wp boilerplate create acf-meta --name=intro

This command will generate a CustomMeta folder inside src folder and add a new file called IntroAcfMeta.php. Inside that file, you should see the following method:

public function fields(): void
{
	if (function_exists('acf_add_local_field_group')) {
		\acf_add_local_field_group([]);
	}
}

Go back to your PHP code export for ACF fields and select everything inside the acf_add_local_field_group() function and paste it into your function. To make it in line with our coding standards, we have to do the following:

• replace array() with []
• make every label translatable and escaped - use esc_html__()
• instead of hardcoding the field name, replace it with a class constant

After all these changes, your code should look like this:

class IntroAcfMeta extends AbstractAcfMeta
{

	/**
	 * Intro field name.
	 */
	public const INTRO_FIELD_NAME = 'intro';

	/**
	 * Render acf fields.
	 *
	 * @return void
	 */
	public function fields(): void
	{
		if (function_exists('acf_add_local_field_group')) {
			\acf_add_local_field_group([
				'key' => 'group_6269300acefda',
				'title' =>  \esc_html__('Intro', 'eightshift-theme'),
				'fields' => [
					[
						'key' => 'field_6269300f8029b',
						'label' => \esc_html__('Intro', 'eightshift-theme'),
						'name' => self::INTRO_FIELD_NAME,
						'type' => 'text',
						// ...
					]
				]
				// ...
			]);
		}
	}
}

The final step is to go back to the Custom Fields in WP admin and either delete or deactivate your field group from there, to prevent registering the fields twice. After adding field definitions in PHP and removing them in WP admin, your field should be visible when editing posts.

Using get_field()​

To fetch the saved meta value, we use ACF's get_field() function, but here are a few tips that could improve your code quality. First, you should check if that function exists. That way, if ACF is deactivated on your site for whatever reason, your site won't break. The second tip is to use a class constant instead of hardcoding the field name. With these practices in mind, your code should look like this:

use YourNamespace\CustomMeta\IntroAcfMeta;

// ...

if (function_exists('get_field')) {
	$introText = get_field(IntroAcfMeta::INTRO_FIELD_NAME, $postId);
}

Theme Options​

ACF's Options page has a wide array of uses and it's very likely that you'll need some sort of Theme Options in your project. To make the implementation of Theme Options a bit easier, we have a CLI command which generates the ThemeOptions class in your project. Just use the following command:

wp boilerplate create theme-options

This command generates a class with two methods. The first one, createThemeOptionsPage() creates a Theme Options page and adds it to the WP Admin sidebar. The second one, registerThemeOptions(), is what registers the fields you will have in Theme Options. Here is an example how Theme Options look after being created using wp boilerplate:

To add fields to your Theme Options, follow the steps from the Exporting PHP code section of this post and add the fields inside the 'fields' => [] array.

Tip - create a helper class​

In this blog post, we covered the whole process of registering and using ACF fields in your project. But, if you are using a lot of ACF fields, wrapping each get_field() function with a function_exists() conditional may become tedious at some point. For that reason, it may be a good idea to create a helper class that you can use for ACF functions.

I won't cover the whole process in detail, but I'll give you some general pointers.

• when registering plugin-related classes, use the Plugins namespace. In this case, you should have namespace YourNamespace\Plugins\Acf
• inside that namespace, you can create a class called AcfHelper
• add a method getField which accepts the same arguments as the get_field() function
• add a method getThemeOption which only accepts one argument, the field name, and the second argument is hardcoded
• use early returns in your methods

if (!function_exists('get_field')) {
	return '';
}

Adding images​

Similar to fonts, there is also a dedicated folder for adding images that will be used in a theme. The location of this folder is assets/images. The procedure to add images is even simpler than fonts, which you can read about in Adding fonts blog post. Just follow these steps to add a new image:

• add the image in inside assets/images folder
• include it in assets/images/index.js
• run npm start to rebuild assets

The new image will now be available in the public folder. The use case for this is adding a favicon or a logo to your project. To use this image in one of your templates or blocks, you have to add the following in your php file:

use YourNamespace\Manifest\Manifest;
// ...

apply_filters(Manifest::MANIFEST_ITEM, 'logo.svg');

The filter we are using is called manifest-item and we use it to get the URL of the asset from the public folder. You can read more about this in our documentation.

You can see how this is being used for rendering both favicon and header logo in your theme's header.php file.

For better organization, you can add additional folders (e.g. icons, placeholders) inside the assets/images folder. Here's an example of how to include them:

// Icons
import './icons/upload.svg';

// Placeholders
import './placeholders/post.png';
import './placeholders/page.png';

Using SVG files from manifest​

If you recall from a previous blog post about Modifying Blocks, you might have already seen an alternative approach to including SVG files in your block or component.

Open src/Blocks/components/quote/manifest.json and you'll see that the icon used by the component is defined inside resources as a key-value pair. Key represents the name that we will use to fetch the icon, while the value is SVG code.

"resources": {
	"icon": "<svg fill='none' height='24' viewBox='0 0 24 24' width='24' xmlns='http://www.w3.org/2000/svg'>...</svg>"
}

In order to make the minification of SVG files as easy as possible, our teammate Goran made an awesome tool called SVG2WP. Some of the options include making attributes JSX compatible, or replacing the color value with currentColor, which can then be used to change the SVG color through CSS.

You've already seen the use of currentColor in the above-mentioned blog post, where we've modified the color of the SVG.

The output of the icon on frontend is very simple. In the Quote component, it was done the following way:

<?php $manifest = Components::getManifest(__DIR__); ?>

<i class="<?php echo \esc_attr("{$componentClass}__icon"); ?>">
	<?php echo $manifest['resources']['icon']; // phpcs:ignore Eightshift.Security.ComponentsEscape.OutputNotEscaped ?>
</i>

An excellent example, where you can see in even more detail how SVGs are being used, is our icon component. It isn't included in Eightshift theme by default, so you have to add it to your project with WP CLI. To include it in your project, use the following command:

wp boilerplate blocks use-component --name=icon

If you include the Icon component inside a block, you will have the option to choose between multiple icons defined in the manifest. Another way to render SVGs from the Icon component is by using the Components::render helper method:

echo Components::render(
	'icon',
	[
		'blockClass' => $componentClass,
		'iconName' => 'download',
	]
);

Here are some examples of icons available out-of-the-box in our Icon component:

Using icons for editor and block options​

When developing your blocks and adding new options, you may need to add icons to improve the user experience. We have many icons already available for use. You can see the full list in our component library under UI icons and Block icons section. We already added the icon when adding a new Color Theme option for the Quote block. Here is the simplified version:

import { ColorPaletteCustom, IconLabel, icons } from '@eightshift/frontend-libs/scripts';

return (
	<ColorPaletteCustom
		label={<IconLabel icon={icons.color} label={__('Color Theme', 'es-theme')} />}
		// ...
	/>
);

This was the end result when we were adding a new option in our Quote block:

Conclusion​

As you could see in this blog post, there are multiple ways of adding assets to a project. It all depends on how these will be used and what the scope of their use will be.

Importing fonts into your project​

Our documentation covers the necessary steps to add a font to your project, but here we'll cover the process in a bit more detail. To start, we need a font (or two). For this example, I'll use Source Sans Pro and Noto Serif which I've downloaded from Google Fonts. They are in the .ttf format (you may find some which are .otf, which will work in the same way), so you need to convert them to .woff and .woff2. Whatever approach you use is okay - we recommend the following tools:

• Convertio
• Cloud Convert
• Everything Fonts
• Transfonter

Fonts should go inside your theme's /assets/fonts folder. Copy the fonts you want to use there. You will also notice that this folder contains an index.js file, used to import fonts into your project. Here's an example of how I imported my fonts:

// SourceSansPro WOFF
import './SourceSansPro-Bold.woff';
import './SourceSansPro-BoldItalic.woff';
import './SourceSansPro-Italic.woff';
import './SourceSansPro-Regular.woff';
import './SourceSansPro-Light.woff';
import './SourceSansPro-LightItalic.woff';

// SourceSansPro WOFF2
import './SourceSansPro-Bold.woff2';
import './SourceSansPro-BoldItalic.woff2';
import './SourceSansPro-Italic.woff2';
import './SourceSansPro-Regular.woff2';
import './SourceSansPro-Light.woff2';
import './SourceSansPro-LightItalic.woff2';

// NotoSerif WOFF
import './NotoSerif-Bold.woff';
import './NotoSerif-BoldItalic.woff';
import './NotoSerif-Italic.woff';
import './NotoSerif-Regular.woff';

// NotoSerif WOFF2
import './NotoSerif-Bold.woff2';
import './NotoSerif-BoldItalic.woff2';
import './NotoSerif-Italic.woff2';
import './NotoSerif-Regular.woff2';

To add these fonts as your base font and secondary font, go to the global manifest located in /src/Blocks and add the following inside globalVariables:

"globalVariables": {
	// ...
	"baseFont": "SourceSansPro",
	"secondaryFont": "NotoSerif",
	// ...
}

Next, you can create a new file called _typography.scss inside your /assets/styles/parts/utils/ folder and add the following:

@include font-face(global-settings(baseFont), 'SourceSansPro-Light', 300);
@include font-face(global-settings(baseFont), 'SourceSansPro-LightItalic', 300, italic);
@include font-face(global-settings(baseFont), 'SourceSansPro-Regular', 400);
@include font-face(global-settings(baseFont), 'SourceSansPro-Italic', 400, italic);
@include font-face(global-settings(baseFont), 'SourceSansPro-Bold', 700);
@include font-face(global-settings(baseFont), 'SourceSansPro-BoldItalic', 700, italic);

@include font-face(global-settings(secondaryFont), 'NotoSerif-Bold', 700);
@include font-face(global-settings(secondaryFont), 'NotoSerif-BoldItalic', 700, italic);
@include font-face(global-settings(secondaryFont), 'NotoSerif-Italic', 400, italic);
@include font-face(global-settings(secondaryFont), 'NotoSerif-Regular', 400);