Summary

This month we hosted three Build Mode Live calls. During one call, Sam Munoz gave a presentation called “Book Now, Work Later” which focused on how to market your WordPress business to get paid now. Brian Gardner also led a heartfelt call centering on mental health in the WordPress world. Finally, Nick Diego joined the final call for a lively discussion about the future of WordPress.

Resources & Links

We share a lot of resources during these sessions, here are some of the most valuable references made this month:

• Book Now, Work Later Slides presentation by Sam Munoz

What’s Next for Build Mode

We haven’t decided on the topics for next year – but you can help!

Head over to the @wpebuilders Twitter and share what you’d like to discuss about WordPress as we kick off 2023. 🎉

If you are interested in attending an upcoming Build Mode session, you can sign up using this link and join us.

Here’s the list of January 2023’s sessions. All calls are at 11 am ET:

• January 6, 2023
• January 13, 2023
• January 20, 2023
• January 27, 2023

Let us know you’ll be there by tagging or DM-ing us on Twitter, @hellosammunoz and @bgardner. You can also follow along with topics and feedback with #BuildModeLive on Twitter.

Until next time, start building! 🛠

The post Build Mode Live: December 2022 Sessions appeared first on Builders.

Builders Workshops are live events exploring features of modern WordPress with the WP Engine Developer Relations team.

This workshop was hosted by Damon Cook and took place on December 14^th, 2022.

In this special ACF PRO workshop we covered:

• Setting up an ACF PRO Repeater field for accordion items.
• Scaffolding a plugin and nested block with the @wordpress/create-block package and the custom @colorful-tones/acf-create-block-template package.
• Migrating ACF PRO field registration from ACF PRO’s UI into the plugin (with JSON file).
• Styling and hooking up the accordion JavaScript with 10up’s handy @10up/component-accordion

Here is the video recording 👇

When is the next Builders Workshop?

We’ll be announcing some workshops in the New Year. Please be sure to follow @wpebuilders for announcements.

Also, reach out and let us know what you might want to see in an upcoming workshop. Be sure to mention @dcook or @wpebuilders and use the tag #BuildersWorkshop

The post Builders Workshop – Build an accordion block with ACF PRO appeared first on Builders.

Summary

This month we hosted three Build Mode Live calls. During these calls we discussed the stability of future WordPress releases, what it means to be a WordPress developer today, and what builders still want to see brought into WordPress core.

Key Takeaways

• The idea of being a “WordPress Developer” has shifted – there are some feelings within the community about not feeling qualified enough to be referred to as a “developer” anymore
• There are nuanced differences between the terms: users, developers, builders, and clients – and how they interact with WordPress
• Builders have a lot of feature requests to improve WordPress core including:
  • being able to set a default featured image
  • media replace
  • the ability to create a quick post (like this plugin)
  • SVG support
  • folders for pages
  • simple page ordering
  • reordering columns on mobile (and other smaller responsiveness features)
  • forms
  • accessibility by default

Resources & Links

We share a lot of resources during these sessions, here are some of the most valuable references made this month:

• What a Semantic Patterns in WordPress? by Nick Diego
• TT3 default theme: Announcing style variation selections on WordPress.org
• Create Block WordPress Block Editor Handbook
• Genesis Blocks by StudioPress
• An Introduction to Spacing Presets by Brian Gardner
• AinoBlocks by ElmaStudio
• My Eyes are Up Here WordPress plugin for smart image cropping

What’s Next for Build Mode

As we approach the end of the year, we will focus on more human-centered topics during the December Build Mode sessions.

• Business focused conversations such as how to book projects this year that you start next year.
  
• A conversation about mental health as a WordPress builder or developer
  
• Marketing and lead generation as a freelance WordPress expert

If you are interested in attending an upcoming Build Mode session, you can sign up using this link and join us.

Here’s the list of December 2022’s sessions. All calls are at 11 am ET:

• December 2, 2022
• December 9, 2022
• December 16, 2022

Let us know you’ll be there by tagging or DM-ing us on Twitter, @hellosammunoz and @bgardner. You can also follow along with topics and feedback with #BuildModeLive on Twitter.

Until next time, start building! 🛠

The post Build Mode Live: November 2022 Sessions appeared first on Builders.

We’ll assume you have some basic familiarity with Composer and WPackagist, but if you don’t, here is an excellent resource to get you started: Managing your WordPress site with Git and Composer.

Here is what we’ll be covering:

• Version control (Git) – you will only need the wp-content/ directory to be under version control. We’ll let WP Engine maintain WordPress core automatic updates.
• Composer – you will use Composer and WPackagist.org to manage WordPress plugins, including:
  • Advanced Custom Fields PRO – we’ll show you how to pull in ACF PRO with Composer using the ffraenz/private-composer-installed package.

Overview of project organization

Here is an overview of how the site is currently organized in our WordPress install’s wp-content/.

We’ll reference the table above to create our .gitignore file. Note: we’re not putting other standard WordPress directories within the wp-content/ directory under version control, e.g. wp-content/uploads, wp-content/upgrade, wp-content/mu-plugins, because we want to keep things lean.

#---------------------------
# WordPress general
#---------------------------
/index.php

#---------------------------
# WordPress themes
#---------------------------
/themes/*
!/themes/custom-theme

#---------------------------
# WordPress plugins
#---------------------------
/plugins/*
!/plugins/custom-plugin

#---------------------------
# WP MU plugins: these are
# managed by the platform.
#---------------------------
/mu-plugins/

#---------------------------
# WP uploads directory
#---------------------------
/uploads/

#---------------------------
# WP upgrade files
#---------------------------
/upgrade/

#---------------------------
# Composer
#---------------------------
/vendor
.env
.env.*
!.env.example
Code language: plaintext (plaintext)

In the snippet above, we’ve added the items we’ll want to ignore that are associated with our Composer setup (last few lines). Let’s dig in on that next.

Set up Composer

First, we’ll want to pull in the pragmatic composer/installers package. We’ll use this Composer package to set our custom paths where we want our WordPress plugins installed by Composer.

{
    "name": "wpe/demo-project",
    "type": "project",
    "require": {
        "composer/installers": "~1.0"
    },
    "extra": {
        "installer-paths": {
            "plugins/{$name}": [
                "type:wordpress-plugin"
            ]
        }
    }
}
Code language: JSON / JSON with Comments (json)

In the code snippet above, we require composer/installers, set installer-paths for any Composer dependencies with the "type:wordpress-plugin" to be installed in the plugins/ directory, and we pass the {$name} of the plugin. We won’t see much progress if we run composer install at this point, but composer/installers should be installed.

WPackagist set up in Composer

Next, we’ll want to set up our WPackagist integration to pull in our WordPress project’s plugins.

{
    "name": "wpe/demo-project",
    "type": "project",
    "repositories": [
        {
            "type": "composer",
            "url": "https://wpackagist.org"
        }
    ],
    "require": {
        "composer/installers": "~1.0",
        "wpackagist-plugin/duplicate-post": "^4.5",
        "wpackagist-plugin/svg-support": "^2.5.1",
        "wpackagist-plugin/wordpress-seo": "^19.10"
    },
    "extra": {
        "installer-paths": {
            "plugins/{$name}": [
                "type:wordpress-plugin"
            ]
        }
    }
}
Code language: JSON / JSON with Comments (json)

To pull in plugins from WPackagist, we have to tell Composer to reference WPackagist as a package source, which is accomplished with the repositories key. Then all we have to do is require all of our WPackagist plugins.

ACF PRO set up in Composer

ACF PRO requires a license key, but that is no sweat, thanks to Fränz Friederes’ private-composer-installer Composer package. This package allows us to reference a URL and pass along a variable for our secret license key. The emphasis here is secret. We don’t want to store our license key anywhere that is publicly available. We’ll keep our license key in a .env file. The .env file is a standard way to store environmental variables, which should exist outside the code.

{
    "name": "wpe/demo-project",
    "type": "project",
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "advanced-custom-fields/advanced-custom-fields-pro",
                "version": "6.0.5",
                "type": "wordpress-plugin",
                "dist": {
                    "type": "zip",
                    "url": "https://connect.advancedcustomfields.com/index.php?a=download&p=pro&k={%PLUGIN_ACF_KEY}&t={%VERSION}"
                }
            }
        },
        {
            "type": "composer",
            "url": "https://wpackagist.org"
        }
    ],
    "require": {
        "composer/installers": "~1.0",
        "ffraenz/private-composer-installer": "^5.0",
        "wpackagist-plugin/duplicate-post": "^4.5",
        "wpackagist-plugin/svg-support": "^2.5.1",
        "wpackagist-plugin/wordpress-seo": "^19.10",
        "advanced-custom-fields/advanced-custom-fields-pro": "*"
    },
    "extra": {
        "installer-paths": {
            "plugins/{$name}": [
                "type:wordpress-plugin"
            ]
        },
        "private-composer-installer": {
            "dotenv-path": ".",
            "dotenv-name": ".env"
        }
    }
}

Code language: JSON / JSON with Comments (json)

As you can see, we’ve added the ACF PRO download URL as a reference point in our repositories key. We’ve also added the ffraenz/private-composer-installer and advanced-custom-fields/advanced-custom-fields-pro as required packages. Last, we tell the private-composer-installer where we want our .env file to reside in relation to our composer.json file within our project.

You can check out the full demo project’s composer.json here.

Create .env file with ACF PRO key

All that is left to do is create our .env file and place our ACF PRO license key.

PLUGIN_ACF_KEY=replacewithyourkey
Code language: plaintext (plaintext)

With all of our Composer dependencies established, we should be able to run composer install and have everything pulled into our project.

Set up deployment actions

Now that we have all our Composer dependencies set up. We’ll integrate our deployment actions. This will allow us to deploy any custom updates to our custom plugin (wp-content/plugins/custom-plugin) and theme (wp-content/themes/custom-theme) alongside our latest WPackagist or ACF Pro updates.

We’ll be using WP Engine’s official Deploy WordPress to WP Engine GitHub Action for this part. We’ve already covered all the steps to set this workflow up and highly recommend you have your SSH key established on WP Engine and within your GitHub repo.

Establish include and exclude rsync options

The key difference for this new set up is that we want to exclude some files and folders from the rsync process. Below is our final YAML workflow file.

name: Deploy to WP Engine production environment
on:
  push:
    branches:
     - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

    - name: GitHub Action Deploy to WP Engine
      uses: wpengine/github-action-wpe-site-deploy@v3
      with:
        # Deploy vars
        WPE_SSHG_KEY_PRIVATE: ${{ secrets.WPE_SSHG_KEY_PRIVATE }}
        WPE_ENV: qorp
        # Deploy Options
        REMOTE_PATH: "wp-content/"
        FLAGS: -azvr --inplace --delete --include-from config/include.txt --exclude=".*" --exclude-from config/exclude.txt
        PHP_LINT: TRUE
        SCRIPT: wp-content/config/post-deploy.sh
Code language: YAML (yaml)

The notable differences for this set up are highlighted above (the last four lines).

You’ll notice that we’re passing the FLAGS parameter, and it is referencing a config/include.txt file and a config/exclude.txt file. These are key to telling our workflow what files and folders we do and don’t want to deploy.

Let’s create these:

# Including plugins/themes that we check into git so that the version in github is deployed
/plugins/custom-plugin
/themes/custom-theme
Code language: plaintext (plaintext)

# Excluding these items from being deleted each sync
plugins/*
themes/* 
mu-plugins/
uploads/
blogs.dir/
upgrade/*
backup-db/*
advanced-cache.php
wp-cache-config.php
cache/*
cache/supercache/*
index.php
mysql.sql

.env
.env.*
vendor
Code language: plaintext (plaintext)

Create post-deploy script

After our GitHub Action performs all the syncing we have the option to run a script. This is how we’ll handle running Composer on the final production server. This way we’ll keep our repository small and only version control what we need to and let Composer run on the final server.

cd wp-content && composer install --optimize-autoloader --no-dev --no-progress
Code language: Bash (bash)

Bonus: PHP linting

The WP Engine GitHub action allows us to lint our code with PHP_LINT: TRUE and checks for syntax errors. It will not test for fatal errors, which is essential to note.

Conclusion

Utilizing Composer with WPackagist to manage your WordPress plugin dependencies can help keep teams organized and facilitate consistent workflows.

Also, keep in mind that there are many different ways to organize and deploy code. Let us know how you’re maintaining your ideal workflow—tag me on Twitter @dcook.

The post Using Composer to Manage Plugins and Deploy to WP Engine appeared first on Builders.

This article will explore two block layouts that rely on the Columns block. While both are relatively simple, they demonstrate how powerful and versatile this block can be. We will also add additional functionality using custom CSS classes. Let’s get started.

Feel free to watch the video version of this article or continue reading.

Overview

Before diving in, it’s important to note that this article will not cover everything related to the Columns block.

If you have never used the Columns block before, the best way to explore this block type is to open up the Editor. Insert a Columns block and add a few additional columns. Manipulate the color, dimension, border, and alignment settings. Just start playing around. The companion video above does provide a brief walkthrough at the beginning.

Once you’re comfortable with how the block generally works, you will be ready for some of the more advanced implementations discussed in this article. And if you would like to follow along at home, all examples and screenshots were created using WordPress 6.1, the latest version of Gutenberg, and Frost.

Frost is an experimental block theme developed and maintained by the Developer Relations team here at WP Engine. I also recommend the Twenty Twenty-Three theme as a good starting point when exploring new features in WordPress.

When columns are the best tool for the job

There are countless applications where the Columns block is the obvious choice. Say you need three columns of content that showcase the features of a product or the services of a business.

You will use this type of layout often, and it’s good to get comfortable building them quickly and efficiently while utilizing all of the design tools available to the Columns block.

Let’s set this design aside and look at a scenario where the Columns block might not be the obvious first choice. Consider this layout that uses the Media & Text block.

As the name implies, the Media & Text block allows you to display an image to the left or right of text content. The block has some useful features, such as the ability to stack the image and text on mobile, but there are design elements that you cannot configure in the Editor without custom CSS. A good example is the space between the image and the content. You also can only modify the size of the image. No duotone, no caption, the list goes on.

This block sacrifices control for a simplified user interface. This might be an acceptable trade-off in many situations, but these limitations can be frustrating from a design perspective. The correct tool for this type of layout, in my opinion, is the Columns block. The block layout becomes a bit more complicated, but you can build precisely what you want.

Step 1 – Setup

Start by adding a Columns block where each internal Column block is set to 50% wide. Add some content to the left Column and use a Cover block to add an image to the right Column. You can also use a simple Image block, but the Cover block provides additional features that this layout will need. Finally, configure a background color and modify the text and button colors as needed.

The design is already beginning to resemble the Media & Text block, but let’s keep going.

Step 2 – Dimensions

By default, padding is added to the Columns block when a background color is set. You can remove this while also setting the block spacing between the columns to zero in the Dimensions panel. We will control the visual space between the image and text by applying padding to the left internal Column block.

The screenshot below shows the padding around the text content, while padding and block spacing have been zeroed out on the Columns block.

The general layout is now complete so let’s move on to the image.

Step 3 – Image Adjustments

Since we are using a Cover block, there are lots of modifications that can be made. Let’s apply a duotone to the image and add a small caption. Finally, we can set the height of the image using the Min Height setting in the Dimensions panel.

Here’s a comparison of the two completed designs. Note that the Media & Text does use fewer blocks and requires less configuration by the user. There’s always a tradeoff, but you can build far more robust designs using the Columns block, and you can always pre-package them as block patterns for end-users.

The one downside of this approach is that we cannot display the image above the text content on mobile if the image is placed in the right Column block. Let’s fix that.

Bonus – How to reverse column direction on mobile

The ability to change the order of stacked columns on mobile is not natively supported within WordPress (yet). Columns retain their order.

However, you can easily add this functionality with a custom class and some CSS. In the theme’s style.css file, let’s add the following.

@media (max-width: 782px) {
    .mobile-reverse-column-direction {
        flex-direction: column-reverse;
    }
}
Code language: CSS (css)

The Columns block is a flexbox container, which means that you can reverse the direction of the items within it using flex-direction. To ensure this styling is only applied on mobile, wrap the class in a simple media query at the breakpoint you wish.

By default,782px is browser width when columns stack on mobile in WordPress, which is why I chose it for this example.

Finally, add mobile-reverse-column-direction to the Columns block. The image will now appear above the content on mobile.

You should always use as many native block settings as possible before writing CSS, but a little bit of custom CSS goes a long way, as seen below.

Using highly specific utility classes is generally the best approach if you need additional styling. If WordPress adds new functionality, like the ability to reverse the direction of columns on mobile, you can easily remove the utility class.

While the result is visually quite similar to the Media & Text block, you have far more control over each design element when using the Columns block. Now let’s explore the Columns block in the context of the Site Editor.

Using columns to create a page template with a sidebar

Sidebars are a standard fixture in web design. Unfortunately, the Frost theme does not include a page or post template with a sidebar. Luckily you can fix that with the help of the Columns block.

Begin by navigating to the Site Editor and then create a new custom template. Name it whatever you wish. This template will be available for both posts and pages.

Once you click “Create,” WordPress will copy the default page template as a starting point for your custom design.

Every block theme is different, but the default page template for Frost is quite simple. It consists of Header and Footer template parts that sandwich a Group block containing the Post Title and Post Content blocks.

Before adding a Columns block and modifying the design, you will want to ensure the outer Group block has layout enabled. Enabling layout is not needed in Frost’s default template but will allow you to set the alignment of the Columns block, which will be placed inside the Group.

See the screenshot below for reference. You can learn more about alignment and layout controls in our recent article here on WP Engine Builders.

With layout enabled on the Group, you can remove the original content and add a Columns block. This is your opportunity to get creative and design a sidebar that suits the needs of your project. For the design below, here are a few of the specific tweaks that were made.

Design Features

• The Columns block alignment is set to Wide, so it lines up with the header and footer.
• A two-column layout was used, one with a width of 25% and the other with 75%.
• The block spacing between the two columns was set to Medium.
• The Post Content block was justified to the left.
• Three separate sidebar content items were created: two calls to action and a list of post categories.

The companion video at the beginning of this article contains a complete walkthrough of how this template was designed.

Before finishing the template, let’s apply the mobile-reverse-column-direction class to the Columns block. Otherwise, the sidebar will display above the post content on mobile devices. Not an ideal user experience.

After saving the template in the Site Editor, it will become available when editing posts and pages. Choose a post and set the template to the new custom page template. The final result should look something like this.

Bonus – How to make a sticky sidebar

The custom page template looks great, but we can take this design further with another minor CSS tweak. What if the sidebar content was “sticky,” so it stuck to the top of the browser window as the user scrolled down the post?

Sticky sidebars are relatively common on the web when you want to ensure specific content is always displayed to a visitor. Examples include calls to action, advertisements, or a post’s table of contents.

Unfortunately, making the sidebar Column block sticky is a bit challenging, given that the parent Columns block is a flexbox container. Applying custom CSS to the content within the Column is much easier.

To do so, we need to modify the block layout in the sidebar slightly by containing all of the content within a Group block. Then apply the CSS class sticky-column-content to the Group.

Next, add the CSS for the custom class to the theme’s stylesheet.

.sticky-column-content {
    postion: sticky;
    top: 30px;
}
Code language: CSS (css)

The top spacing is relatively arbitrary but ensures a small buffer between the top of the browser window and the sidebar content. And here is the final result in action.

In conclusion

The Columns block is one of the most powerful tools at your disposal when building block layouts. Hopefully, the two relatively simple examples in this article demonstrated just how versatile it can be. Blocks continue to get more powerful with each WordPress release, and it’s incredible how much you can accomplish with very little extra CSS. By WordPress 6.2, you might not even need the custom CSS classes used in this article.

So have you experimented with this block type or used any of these techniques in your projects? Let me know on Twitter. I’d love to take a look.

And if you’re looking for more modern WordPress development techniques, check out our other posts here on WP Engine Builders. Until next time.

The post Designing with Column Blocks in WordPress appeared first on Builders.

Build Mode Workshops are live events exploring features of modern WordPress with the WP Engine Developer Relations team. This workshop was hosted by Damon Cook and took place on November 15^th, 2022.

In this recent workshop we covered:

• Setting up a simple WordPress plugin and scaffolding a custom block with @wordpress/create-block
• Dependency management in a custom block
• Registering and writing an accordion block
• Light styling with theming in mind

Here is the video recording. 👇

Resources & Links

Accordions are not always an ideal user experience, and careful consideration is warranted.

• Why <details> is Not an Accordion
• Details / Summary Are Not [insert control here]
• W3C Accordion Example

Key takeaways

The attendees had a lot of great questions about custom block development. A majority responded that they had never tried creating a custom block before.

When is the next Build Mode Workshop?

We’ll be announcing next month’s workshop soon. Please be sure to follow @wpebuilders for announcements.

Also, reach out and let us know what you might want to see in an upcoming workshop. Be sure to mention @dcook or @wpebuilders and use the tag #BuildModeWorkshop

The post Build Mode Workshop – November 2022 appeared first on Builders.

By the end of this tutorial, you’ll be able to push changes to a designated branch, and it will automatically deploy those changes to a respective WP Engine environment.

We’re going to start from the very beginning. Let me introduce you to my new client: Qorp. Qorp has engaged my expertise in creating a new WordPress site for them and they’re eager to get their site launched on WP Engine’s hosting platform.

I’ve had several meetings with Qorp, and we’ve nailed down the requirements for the site. I’ve already started creating a sandbox site on my computer using WP Engine’s Local. I’ve made good progress dialing in a WordPress theme and even created a simple WordPress plugin to register a simple custom block I’m developing for their site.

Now, I need to take my sandbox site in Local, put it under version control, and deploy the code to the client’s staging environment for them to review.

Initialize Git for our Local WordPress site

Let’s start using Local’s “Open site shell” to open our command line tool. You can access this by either right-clicking on the site or directly below the site title; there is also an “Open site shell” option.

Once our command line tool opens, it will drop us into the root of our WordPress site’s installation on our local computer’s hard drive. We’ll want to move into the wp-content/ directory. So, type cd wp-content and Enter to drop into the wp-content/ directory. Now we can run git init to initialize Git version control in our wp-content/ directory. Now the entire directory is under version control. 💥

Smart Plugin Manager

However, we don’t want the entire wp-content/ directory under version control because we’ll utilize WP Engine’s Smart Plugin Manager to maintain the updates on most of our everyday plugins, like Yoast SEO and Safe SVG.

Smart Plugin Manager automates the overhead of updating our WordPress plugins and is smart enough to detect critical errors during the upgrade process and roll back if anything is detected. We can assure Qorp that their site will always be up to date with the latest WordPress core files and the latest WordPress plugin updates, which should help both parties feel confident and secure.

Repo organization and .gitignore

We can create a .gitignore file in our wp-content/ directory to tell Git what we want to ignore in our version control.

We’ll use the table above and create our .gitignore file based on this desired structure. First, type touch .gitignore to create a new .gitignore file and open it in your code editor of choice (😉 I recommend VS Code, and if you already have it installed, then type code . to open the current directory).

Here is what we’ll want in our .gitignore to properly organize our ignore folders and files.

#---------------------------
# Themes
#---------------------------
# Ignore all themes
/themes/*
# Except this one theme
!/themes/qorp-theme

#---------------------------
# Plugins
# Check out WPE's Smart
# Plugin Manager (SMP)
#---------------------------
# Ignore all plugins
/plugins/*
# Except this one plugin
!/plugins/qorp-plugin

#---------------------------
# MU plugins: these are
# managed by the platform.
#---------------------------
/mu-plugins/

#---------------------------
# Uploads directory
#---------------------------
/uploads/

#---------------------------
# Upgrade files
#---------------------------
/upgrade/
Code language: PHP (php)

With this .gitignore saved, we should see our VS Code update to show the following folders ignored in the Explorer.

VS Code Explorer with empty .gitignore file

VS Code Explorer with ideal.gitignore file

We’ll need to commit our changes and push them up to our GitHub remote repository, which we assume you already created with your GitHub account.

First, we’ll add our remote repository: git remote add origin https://github.com/[your-username]/[your-repo].git. Be sure to replace that last string with your remote GitHub URL.

Next, we’ll commit our work and push it up to this newly added remote with the following commands:

git add -A
git commit -m '💥 initial commit'
git push -u origin main
Code language: JavaScript (javascript)

Integrate GitHub Actions into repo

Now we have our repository organized and pushed to the remote. Next, we’ll start incorporating our GitHub Actions.

Generate SSH key

For our GitHub Actions to be able to interact with our WP Engine site, we need to utilize an SSH key.

ssh-keygen -t ed25519 -f ~/.ssh/wpengine_qorp
Code language: JavaScript (javascript)

Add public SSH key to WP Engine portal

We need to add your newly generated SSH key to the WP Engine user portal.

1. Visit the User Portal > Profile > SSH Keys area
2. Click the ‘Create SSH key’ button (top, right side)
3. We’ll need to copy your newly created SSH key’s public file. Open your command line tool and run the following command to copy the public key to your clipboard: pbcopy < ~/.ssh/wpengine_qorp.pub (Be sure to replace the last bit with your file name)
4. Paste the public key into the ‘New SSH key’ modal and click the ‘Add SSH key’ button

You should now see your SSH key among the ‘My SSH keys’.

Add private SSH key to GitHub repo

1. Go to your GitHub repo’s Settings tab > Secrets > Actions
2. Click the ‘New repository secret’ button (top, right side)
3. We’ll need to copy your newly created SSH key’s private file contents. Open your command line tool and run the following command to copy the private key to your clipboard: pbcopy < ~/.ssh/wpengine_qorp (Be sure to replace the last bit with your file name)
4. Paste the private key into the ‘Secret’ field and the ‘Name’ field should be: WPE_SSHG_KEY_PRIVATE and click the ‘Add secret’ to save.

Add WP Engine GitHub Actions

We’re almost done. We have our GitHub repository organized, our SSH keys generated and installed on WP Engine’s portal, and our private SSH key is saved in our repo’s Action Secrets. Now, we have to write and add our GitHub repo’s workflow action, which makes all the magic 🪄 happen.

Lucky for us, the existing Deploy WordPress to WP Engine GitHub Actions are readily available and well documented.

We’ll add a .github/workflows directory within the root of our repository (Hint: we’re using wp-content/ as the root in this tutorial). We’ll then want to add two YAML files into this new directory:

• .github/workflows/main.yml 👈 handles the deploy to our production site
• .github/workflows/stage.yml 👈 handles the deploy to our staging site

name: Deploy to production
on:
  push:
    branches:
     - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: GitHub Action Deploy to WP Engine
      uses: wpengine/github-action-wpe-site-deploy@v3
      with:
      # Deploy vars
        WPE_SSHG_KEY_PRIVATE: ${{ secrets.WPE_SSHG_KEY_PRIVATE }}
        WPE_ENV: qorp
        # Deploy Options
        REMOTE_PATH: "wp-content/"
        PHP_LINT: TRUE
        CACHE_CLEAR: TRUE
Code language: PHP (php)

name: Deploy to staging
on:
  push:
    branches:
     - stage
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: GitHub Action Deploy to WP Engine
      uses: wpengine/github-action-wpe-site-deploy@v3
      with:
      # Deploy vars
        WPE_SSHG_KEY_PRIVATE: ${{ secrets.WPE_SSHG_KEY_PRIVATE }}
        WPE_ENV: qorpstg
        # Deploy Options
        REMOTE_PATH: "wp-content/"
        PHP_LINT: TRUE
        CACHE_CLEAR: TRUE
Code language: PHP (php)

Some key takeaways from the main.yml and stage.yml files:

• Line 5: represents the GitHub branch that is associated with deploy. Further reading: GitHub Docs > Using workflows > Workflow Syntax: Using filters
• Line 15: WPE_SSHG_KEY_PRIVATE – This points to the repo’s Action Secret variable that we added above: “Add private SSH key to GitHub repo.”
• Line 16: WPE_ENV – This must match the WP Engine environment and represent your target environment.

Here is a full list and description of all of the deploy options for the Deploy WordPress to WP Engine workflow.

With those files added to your repository, you need to commit and push them up to trigger your first deployment:

git add -A
git commit -m "➕ ADD: GitHub Action workflows"
git push
Code language: JavaScript (javascript)

If you want to also deploy to your staging site then run the following commands to create a new stage branch, push and deploy:

git checkout -b stage
git push -u origin stage

Verifying GitHub Actions

You can view pending, successful and failed deploys by visiting your repo’s Actions tab.

Conclusion

Having continuous deployment set up with GitHub Actions can keep things running smoothly. In another upcoming tutorial, we’ll demonstrate how to leverage tools like Composer to manage dependencies and even run code linting to inspect your code for consistency and bugs.

Also, keep in mind that there are many different ways to organize and deploy code. Let us know how you’re maintaining your ideal workflow—tag me on Twitter @dcook.

The post Branched Deploys to WP Engine With Github Actions appeared first on Builders.

Feel free to watch the video version of this article or continue reading.

Overview

We will not be able to cover everything related to block layout, alignment, and dimensions in this single article. But by the end, you should have a solid understanding of key concepts as well as a few tips and tricks that you can apply to your WordPress site or next project.

Note that we will be focusing specifically on block themes. Much of what is discussed here will apply to classic themes so long as they opt into these new design tools, but results may vary. If you would like to follow along at home, all examples and screenshots were created using Frost.

Frost is an experimental block theme developed and maintained by the Developer Relations team here at WP Engine. We also recommend the Twenty Twenty-Three theme as a good starting point when exploring new features in WordPress.

A Primer on Block Layout

Block layout impacts virtually every aspect of a website and is one of the more complicated concepts to fully understand when working with block themes. Therefore, it’s a natural starting point for our exploration.

You have likely seen the alignment toolbar option when editing blocks in the Editor.

For many blocks, this dropdown includes the options for None, Wide width, and Full width, allowing you to configure the block’s width. Notice the pixel values provided for None and Wide width. The theme author sets these values in the theme.json file in the layout subsection of settings and they are applied site-wide.

{
    ...
    "settings": {
        "layout": {
            "contentSize": "640px",
            "wideSize": "1200px"
        },
        ...
    },
    ...
Code language: JavaScript (javascript)

Note that None, or the default content width, is controlled by the contentWidth parameter.

Based on the layout settings in Frost’s theme.json file, any block added to a page or post will be 640px wide. But what about blocks placed inside container blocks, like Groups?

This is where things get a bit tricky.

The site-wide layout settings are applied to blocks at the root level. In other words, blocks that are not contained within other blocks. However, certain container blocks allow you to pass the layout settings down to the blocks within. Any block with this functionality will feature a Layout panel. The Group block is the most common example and the one you will likely use the most often.

When you toggle “Inner blocks use content width, ” the blocks within the Group will receive the layout settings from theme.json. This then allows you to configure the alignment of each child block. Note that regardless of the alignment setting, the actual width of a child block will be restricted by the width of the parent.

One common application of this technique is to apply a background color to a full-width Group block and then place other blocks within, creating a banner effect. In such a design, we want the site-wide layout settings to apply to the children inside the Group. The example below demonstrates how toggling “Inner blocks use content width” enables this functionality.

When “Inner blocks use content width” is enabled, you can also manually set content and wide width settings specifically for the container block. These “local” settings will override the site-wide defaults on every block within the container, which is handy when specific block designs call for unique layouts.

In the gif above, notice how the pixel values in the alignment dropdown of the child Columns block are updated to reflect the Group’s custom layout settings.

For a more visual explanation of block layout, I encourage you to check out the companion video, which provides additional examples.

Alignment and Justification

Block “alignment” encompasses many different controls depending on the block type. For example, text-related blocks generally include text alignment settings. Blocks that are flex containers often have several justification settings. Work was done in WordPress 6.1 to expand and standardize these controls across similar block types.

Given the variety of alignment settings, many of which are block-type specific, we will mainly discuss some alignment tips and tricks in this section. Frankly, these tools are relatively intuitive and just require experimentation to achieve your desired block layout.

Group Justification Tip

In the section above, you likely noticed the justification setting inside of the Layout panel. This functionality is brand new in WordPress 6.1.

Before 6.1, all content was center-justified within blocks that supported layout. This is a reasonable default for most use cases, but there are specific designs where being able to justify the content to the right or left is helpful. Consider the example below.

Here we have a container Group block and manually set the content width 500px for all children blocks, which are then justified to the left. A simple and unique layout that was not possible before without custom CSS.

Row Alignment Tip

Rows blocks have some of the most alignment and justification settings, and you can use them to create quite sophisticated layouts. Take a look at the following example.

Inside the Row block, we have a Group and Paragraph block. The Paragraph contains the “View all” link. Inside the Group, we have a Heading and Paragraph block. We want the Group to be on the left and the link on the right, so we use the “Space between items” justification settings. Finally, we want the “View all” link to be horizontally aligned with the description Paragraph block in the Group. To do so, we set all blocks within the Row to “Align bottom”.

Image Alignment Tip

One common question regarding block alignment is how to align an image such that text wraps around it. This is easy to do in the Classic Editor but becomes a bit more tricky with blocks, especially in block themes like Frost and Twenty Twenty-Three.

If you align an Image block to the left in Frost, the image will float to the screen’s left. Depending on the screen size, it will look something like this.

We just discussed how layout works in block themes. By default, blocks are constrained to the content width, which is 640px in Frost. Without getting too technical, when the image is floated, it’s no longer constrained and floats to the edge of the nearest container.

While this might sound abstract, it’s key to the solution. The floated Image block needs a container to butt up against. So all you need to do is wrap the Image block and the text in a container block. Usually, I would use a Group.

As you can see, the floated Image block is now restricted within the Group block, and the text wraps as you would expect.

Block Spacing and blockGap

Much like layout, block spacing is a fundamental component of block themes. Block spacing, denoted as blockGap in theme.json, provides a site-wide default for the amount of spacing (gap) between blocks. In Frost, all blocks are separated by 30px.

{
    ...
    "styles": {
        "spacing": {
            "blockGap": "30px",
            ...
Code language: JavaScript (javascript)

However, like layout, block spacing can be manually set within the Editor and configured by block type in theme.json. We will save the theme.json discussion for another article, but below, you can see the block spacing settings in the Dimensions panel.

Block spacing is more broadly available than layout settings and is supported in nearly every block that contains children. Whether you want to adjust the gap between buttons, the space between columns, or the distance between blocks within a Group, block spacing is one of the most useful Dimension controls.

Block Spacing Tip

Most blocks only support one value for block spacing. However, there are certain situations where you may want different values for horizontal and vertical spacing, especially for designs that adapt responsively to different devices.

Consider the Columns block, which includes a toggle to stack the individual columns on mobile for a better visual presentation. On desktops, you might want a lot of space between each column. But this might not look very good once the columns are stacked on smaller screens.

Luckily the Columns block now supports horizontal and vertical (axial) spacing in WordPress 6.1. Set one value when the columns are displayed horizontally and another when they are stacked vertically.

As of WordPress 6.1, this functionality is only available on Columns, Gallery, and Social Icons. Future releases of WordPress will likely expand this functionality to other block types that support block spacing.

Margin and Padding

Margin and padding controls are located in the Dimensions panel, along with block spacing. Before WordPress 6.1, few Core blocks supported padding, and only a handful supported margin. There was a concerted effort to expand these design tools to most Core blocks in 6.1, and the result is profound. You can now easily control margin and padding at the individual block level allowing for sophisticated layouts without needing third-party plugins or custom CSS.

Note how toggling the link icon allows you to edit the individual sides. The slider icon enables manual unit input and dimensions can be reset by toggling them on and off from the dropdown menu.

Continual work is being done to improve the editing experience, especially for new users that might not be familiar with the concepts of margin and padding. Spacing visualizers and presets are central to this effort. We will discuss spacing presets in more detail below, but here’s a quick look at how visualizers help you “visualize” your dimension edits.

Margin Tip

In the section above, we discussed blockGap and how this theme.json value defines the default space between all blocks. There are certain situations where you might want to modify or remove blockGap. Knowing that this value is applied to the margin-top of each block allows us to achieve block designs that previously needed custom CSS.

Consider the example of two Cover blocks. By default, there will be a space between each equal to the blockGap. Let’s assume that we want to remove this space so the Covers butt against each other.

Since blockGap is applied to margin-top, set margin-top to zero in the Dimensions panel of the second Cover block, and you are good to go.

Spacing Presets

You might have noticed that we configure dimensions using stepped sliders in many screenshots in the sections above. Newly introduced in WordPress 6.1, this functionality allows theme authors to configure default options for margin, padding, and block spacing in the theme.json file. Rather than setting a specific unit value, the user chooses from the set of spacing presets.

Such an approach makes configuring dimensions easier for users and helps establish consistency across a website. That said, users can still manually set unit values for dimensions, as seen in the screenshot below.

Spacing presets is such a cool new feature that it deserves its own article. Luckily, An Introduction to Spacing Presets has already been written. If you are interested in learning more, that article also details how to implement “fluid spacing” using this functionality.

Conclusion

WordPress gets more and more powerful with each release. WordPress 6.1 was no exception. From expanding dimension controls across most Core blocks to spacing steps and justification controls, sophisticated block layouts are now possible without third-party plugins or extra CSS.

Have you begun implementing these new features on your website or in a new project? I’d love to hear about your favorites. Feel free to reach out on Twitter.

And if you’re looking for more modern WordPress development techniques, check out our other posts here on WP Engine Builders. Until next time.

The post Exploring Block Layout, Alignment, and Dimensions appeared first on Builders.

This overview will explore how to use the fluid spacing and typography features included in the Frost theme to establish an optimal responsive WordPress website experience.

An Introduction to Spacing Presets

With WordPress 6.1, builders can implement consistent spacing of blocks and nested blocks out of the box. This functionality includes preset values of padding, margin, and block gap.

theme.json now supports the definition of custom spacing steps, allowing these preset values to be accessible to users inside the editor.

Like font size, the Frost theme utilizes the t-shirt naming convention (xSmall, Small, Medium, Large, xLarge) for spacing presets, providing a consistent user experience that is easy to understand.

Here is the code that is currently used in Frost to define spacing presets:

{
	"settings": {
		"spacing": {
			"spacingScale": {
				"steps": 0
			},
			"spacingSizes": [
				{
					"name": "xSmall",
					"size": "20px",
					"slug": "x-small"
				},
				{
					"name": "Small",
					"size": "40px",
					"slug": "small"
				},
				{
					"name": "Medium",
					"size": "60px",
					"slug": "medium"
				},
				{
					"name": "Large",
					"size": "80px",
					"slug": "large"
				},
				{
					"name": "xLarge",
					"size": "100px",
					"slug": "x-large"
				}
			]
		}
	}
}
Code language: JSON / JSON with Comments (json)

Below is what users see in the editor for blocks that support it. Each gray line represents a step set in the code above. The default value is 0; as you move the blue toggle to the right, an increase of 20px occurs.

    --wp--preset--spacing--x-small: 20px;
    --wp--preset--spacing--small: 40px;
    --wp--preset--spacing--medium: 60px;
    --wp--preset--spacing--large: 80px;
    --wp--preset--spacing--x-large: 100px;

Note: For blocks that support spacing presets, custom values can still be applied by clicking the Set custom size icon to the left of the Unlink sides icon.

Fluid Spacing

We will soon update Frost with a different value for some of the spacing preset values. This update makes the overall experience more responsive and is called fluid spacing. (View demo of fluid spacing in Frost)

Fluid spacing utilizes the clamp() CSS function to define three parameters: a minimum value, a preferred value, and a maximum allowed value. Fluid spacing is applied to four steps: Small, Medium, Large, and xLarge.

Here is the code used to define spacing presets in theme.json:

{
	"settings": {
		"spacing": {
			"spacingScale": {
				"steps": 0
			},
			"spacingSizes": [
				{
					"name": "xSmall",
					"size": "20px",
					"slug": "x-small"
				},
				{
					"name": "Small",
					"size": "clamp(20px, 4vw, 40px)",
					"slug": "small"
				},
				{
					"name": "Medium",
					"size": "clamp(30px, 6vw, 60px)",
					"slug": "medium"
				},
				{
					"name": "Large",
					"size": "clamp(40px, 8vw, 80px)",
					"slug": "large"
				},
				{
					"name": "xLarge",
					"size": "clamp(50px, 10vw, 100px)",
					"slug": "x-large"
				}
			]
		}
	}
}
Code language: JSON / JSON with Comments (json)

The post An Introduction to Spacing Presets appeared first on Builders.

Feel free to watch the video version of this article or continue reading.

Overview

There are many ways to lock down and restrict Editor functionality in WordPress. We will not cover them all in this article, but if you would like a complete overview, check out Curating the Editor Experience in the Block Editor Handbook.

We will begin by exploring content locking and advanced theme.json configurations, followed by content-only editing, a new feature in WordPress 6.1.

To demonstrate these three methods of Editor curation, we will be using a sample call-to-action pattern. It looks like this.

If you would like to follow along, here is a gist of the pattern above. Then simply download Frost, or an equivalent block theme, create a new pattern file in the theme’s patterns folder, and copy over the code from the gist. The sample pattern does not include the background image, but you can add your own.

Frost is an experimental block theme developed and maintained by the Developer Relations team here at WP Engine. All screenshots you will see in this article were made using Frost, and so was the content in the companion video. We also recommend the Twenty Twenty-Three theme as a good starting point when exploring new features in WordPress.

Content Locking

The first method that we will review is content locking. Introduced in WordPress 5.9, the block locking API allows you to restrict the movement and removal of blocks in the Editor. You simply need to apply the lock attribute to the markup of any block. This attribute has two options move and remove. When both options are set to true, the block cannot be moved or removed respectively.

The complete markup on a Paragraph block would look something like this:

<!-- wp:paragraph {"lock":{"move":true,"remove":true}} -->
<p> ... </p>
<!-- /wp:paragraph -->
Code language: HTML, XML (xml)

Luckily, the Editor also has a handy user interface for locking blocks, so you will rarely need to apply the locking attributes manually. We have written an entire article here on WP Engine Builders on the block locking API, which goes into much more detail than we will cover here.

Example Implementation

Referencing the screenshot of our sample pattern above, you will see two Group blocks inside a Cover. These blocks are needed to achieve the desired content layout. If they are inadvertently removed, the pattern will break. Content locking provides an easy way to prevent the removal or movement of these blocks, thereby protecting the intended design.

We can also lock all of the inner blocks to get more restrictive. This approach can be useful to ensure every call-to-action has a title, description, and appropriate button links.

The screenshot below details how you can lock a Group block and then automatically apply the lock settings to all internal blocks as well.

When adding content locking to patterns files, it is generally easiest to lock blocks using the user interface within the Editor. When you are happy with the locking setup, copy and paste the block code into the pattern file. This approach saves time and is less error-prone than manually adding lock attributes directly to the markup.

Once the file is saved, the pattern will be locked, preventing layout changes or certain blocks from being inadvertently deleted. This functionality, however, does not limit the design tools available to each block. As a result, users still have complete flexibility over color, typography, border, and more. We will need the following curation method to handle that.

theme.json Settings

In block themes like Frost, the theme.json file is an incredibly powerful tool that provides a “canonical way” to define the settings and styles of the theme. If you are unfamiliar with theme.json or Global Styles, an excellent primer is available in the Block Editor Handbook.

For this article, we will focus on the settings section of theme.json. This is where you can define the theme’s color palette, typography, spacing, opt-in or out of specific design tools, and more. Frost specifies "appearanceTools": true which automatically opts into all design tools currently available in WordPress. While this approach is perfect for an experimental theme designed for educational purposes, it might not suit every scenario.

Example Implementation

Let’s look at our sample pattern, specifically the buttons. Without any modifications to theme.json, the user can control each button’s color, typography, border, and dimensions.

Assume that we are comfortable giving control over color and typography, but we don’t want users to have access to the border-radius, margin, or padding controls. We can easily turn these off in theme.json. The code below will disable them for all blocks site-wide.

{
    ...
    "settings": {
        "blocks": { ... },
        "border": {
            "radius": false
        "spacing": {
            "margin": false,
            "padding": false,
            ...
        },
        ...
    },
    "styles": {
        ...
Code language: JavaScript (javascript)

Alternatively, you might want to restrict functionality depending on the block type, in this case, the Button block. Unless there’s a compelling reason to disable specific design tools entirely, I generally gravitate toward a more targeted approach.

The code example below will only disable the Button block’s radius, margin, or padding controls. Note how we are using the blocks subsection of settings and are defining the name of the block we want to target.

{
    ...
    "settings": {
        "blocks": { 
            "core/button": {
                "border": {
                    "radius": false
                "spacing": {
                    "margin": false,
                    "padding": false
                }      
            }
        },
        ...
    },
    "spacing": {
        ...
Code language: JavaScript (javascript)

Here you can see how this theme.json configuration manifests in the Editor.

It is important to note that theme.json settings are applied globally. In other words, even though we set out to protect our call-to-action pattern design by limiting editing capabilities, these restrictions are applied to every Button block on the website.

When it comes to simplifying the Editor for users, theme.json does a fantastic job. But what if you wanted to apply design tool restrictions within a specific context, i.e. our pattern example, and not the entire site?

Content-only Editing

Recently introduced in WordPress 6.1, content-only editing takes curating the Editor experience to the next level by solving the context issue. This is a new method of locking that can be applied directly to a container block (Cover, Group, Column) using the "templateLock":"contentOnly" attribute and was designed with patterns and templates in mind.

Instead of paraphrasing the official developer note, here is an excerpt from the write-up.

When enabled, the users can only change the nested content inside the block/pattern. The block structure starts behaving as a single unit where the block hierarchy is entirely hidden. The user can only change text and media URLs in the blocks. 

Additionally, block types without content are hidden from the List View and are unable to gain focus within the block list. This makes it harder to break the expected layout.

In locked mode, the inspector controls of the blocks are also disabled. Instead, the sidebar only shows a list of content blocks a user can change.

— Content only editing and other locking updates

The best way to fully understand this new functionality is through an example.

Example Implementation

As mentioned above, content-only editing is only available on container blocks, but luckily our sample pattern is based on a Cover. Therefore, all we need to do is add the attribute "templateLock":"contentOnly" to the Cover block, and we are good to go.

You can do this manually by navigating to the Code Editor or updating the pattern file directly. In the pattern file, you will want to edit the first line of the block content accordingly:

<?php
/**
 * Title: Custom Call-to-Action Pattern
 * Slug: frost/custom-cta
 * Categories: frost-general, featured
 * Viewport Width: 1280
 */
?>
<!-- wp:cover {"templateLock":"contentOnly", "dimRatio":70,"overlayColor":"contrast","minHeight":600,"minHeightUnit":"px","contentPosition":"center center","align":"full","style":{"spacing":{"padding":{"top":"0","right":"0","bottom":"0","left":"0"}},"color":{"duotone":["#000000","#ffffff"]}}} -->
<div class="wp-block-cover alignfull" style="padding-top:0;padding-right:0;padding-bottom:0;padding-left:0;min-height:600px"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-70 has-background-dim"></span><div class="wp-block-cover__inner-container"><!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|50","right":"var:preset|spacing|50","bottom":"var:preset|spacing|50","left":"var:preset|spacing|50"}}},"textColor":"base","layout":{"type":"constrained","justifyContent":"center"}} -->
...
Code language: HTML, XML (xml)

Once applied, only content and media will be editable within the pattern. Notice how the sidebar is virtually empty, providing a much more streamlined and simplified editing experience.

Users can temporarily disable content-only editing by clicking “Modify” in the options dropdown. Currently, any user can access this button. However, future releases of WordPress will likely include methods to disable this functionality for specific users and user roles, much like what’s possible with standard block locking.

While there is currently no user interface to enable content-only editing without editing block code, we will likely see many more enhancements and iterations in the future. This is only the beginning.

Check out this article’s companion video for a more in-depth walkthrough of how this functionality looks and feels in the Editor.

Conclusion

So while there are many ways to curate the Editor in WordPress, content locking, theme.json settings, and content-only editing are the three that I have found the most useful.

Have you used any of these techniques to improve the WordPress editing experience for your users? I’d love to hear about your favorite methods. Feel free to let me know on Twitter. 

And if you’re looking for more modern WordPress development techniques, check out our other posts here on WP Engine Builders. Until next time.

The post 3 Ways to Curate the Editor Experience in WordPress appeared first on Builders.