README

What is Peach Schnapps

Peach Schnapps is our Wordpress site boilerplate based on the roots.io stack, making use of Bedrock for the site structure and the new WP Block Theme functionality for the theme.

Stack

Lando
Bedrock
AlpineJS
TailwindCSS
Parcel
Twig for templating

Pre-requisites

Lando
Composer
An auth.json file in your home directory with your ACF Pro key in it, see here for more info, e.g. ~/.composer/auth.json

{
  "http-basic": {
    "connect.advancedcustomfields.com": {
      "username": "your-key-here",
      "password": "http://wp-playground.lndo.site"
    }
  }
}

Modules

Peach Schnapps comprises of several different modules, designed to be updated separately to ease future development and support on projects.

These modules are:

Navigation
- Simplifies creation and templating of navigation menus within Wordpress, to avoid using wp_nav_menu()
Twiglet
- Allows use of Twig templates within the theme to make working with Blocks easier
Images
- A more flexible way of handling / displaying images. You just output the image at the size you want and it's automatically resized/cropped. Additionally, allows easy conversion to webp. You no longer need to rely on add_image_size() . Allows creation of blocks with image sizing fields - maybe you could pick from a pre-set list, or maybe the end user can just enter some numbers, it's ezpz.
Blocks
- Simplifies the creation, registration and rendering of Gutenberg blocks
Query
- A wrapper around WP_Query to simplify querying posts
Route
- A wrapper around wp_register_rest_route to simplify usage

Theme Folder Structure

/
/acf-json
/build
/build/blocks
/dist
/parts
/src
/src/Blocks
/src/Components
/src/fonts
/src/Patterns

Blocks

Blocks in Peach Schnapps are handled by the giantpeach/blocks library. This library contains some simple wrappers around block creation / registration / rendering to make life easier, and it allows a mixture of ACF Blocks and those using Wordpress Block API directly.

The following blocks are included:

Logo
Banner
Columns
- Column
Image
Button

Creating Blocks

Easy Way

There is a create-block WP CLI command you can run using lando wp create-block <blockname> to scaffold a block.

Manual Way

Additional blocks can easily be created using either ACF Blocks or the Wordpress Block API. The simplest way is to use ACF Blocks, and there's a BlockInterface PHP class interface and several examples to help out (e.g. the Banner block).

For any block where you require more control over the markup in the editor you may want to reach for the Wordpress Block API. Blocks created in either way are fully compatible with each other.

All blocks need to be added to the $blocks variable in the Giantpeach\Schnapps\Blocks class in order to be registered.

Creating an ACF Block

Additional ACF Blocks can easily be created by creating a new folder within the src/blocks folder with a block.json and the PHP class at a minimum.

The block.json should contain the following:

{
  "name": "giantpeach/banner",
  "title": "Banner",
  "description": "Banner Block",
  "category": "formatting",
  "icon": "admin-comments",
  "keywords": ["banner"],
  "acf": {
    "mode": "preview",
    "renderCallback": "Giantpeach\\Blocks\\Banner\\Banner::display"
  },
  "align": "full",
  "supports": {
    "jsx": true
  }
}

The PHP class needs to implement the BlockInterface, here is a minimal example:

<?php

namespace Giantpeach\Blocks\Banner;

use Giantpeach\Blocks\BlockInterface;

class Banner extends Block implements BlockInterface
{
  public $slides;

  public function __construct($slides)
  {
    $this->slides = $slides;
  }

  public static function display()
  {
    $banner = new Banner(get_field('slides'));
    $banner->render();
  }
}

You will then be able to head to ACF > Field Groups and attach any fields you like to the block.

Creating a Wordpress Block

Creating a Wordpress Block is a little more involved and will require you to become familiar with the Wordpress Block API, as well as requiring an additional build step.

These Blocks are harder to reuse outside of the Wordpress Block editor.

Blocks Class

The Giantpeach\Schnapps\Theme\Blocks\Blocks class is where all block and pattern registration is handled. Add your blocks to the $blocks array and they will be registered and useable within the site.

Patterns currently require manual initialisation in the registerPatterns method. You can see an example in the Giantpeach\Schnapps\Theme\Patterns\TitleLinkColumn class.

Block Class

The Giantpeach\Schnapps\Blocks\Block class handles block registration, rendering the twig template and provides some classes to handle font size and block spacing. Each block you create using the create-block command will be set up to inherit from this class but you can always create a specific class that inherits it if the project has certain requirements that aren't covered by the defaults.

Class Properties

$blockName - e.g. 'giantpeach/block'

$isAdmin - true if in the block editor, false if viewing block on the front end. Useful if you need to apply specific styling in the admin

$blockSpacing - an array of different padding for use on the block

$classes - an array of classes for use in the template, e.g. {{ classes.block.spacing }}

Class Methods

getClasses() - constructs the $classes array

render() - renders the view.twig template if found, otherwise renders the template.php template instead

getBlockName() - returns the block name

registerBlock() - loads and registers the block.json

display() - used to create and render the block in the block editor

getBlockNameFromDir()

Patterns

Patterns are collections of blocks that you can drop into the page. You click the pattern and the blocks that make up the pattern are inserted into the page, ready for you to edit.

It’s also possible to create a new pattern, either in code or via the admin interface (which will be saved within the DB).

Wordpress Block editor

Wodpress uses JS & React to create components in CMS. You can use src/Editor/editor.js file to make changes.

To compile editor script use npm run dev-editor command. It will output the files to /dist/editor. These files are connected with CMS in Schnapps.php blockEditorScripts function

giantpeach / schnapps

Maintainers

Details