giantpeach / schnapps
Peach Schnapps is a WordPress starter theme based on the Roots Bedrock framework.
Installs: 26
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Type:project
Requires
- php: >=8.0
- composer/installers: ^2.2
- giantpeach/blocks: ^1
- giantpeach/config: ^1
- giantpeach/images: ^1
- giantpeach/login-page: ^1
- giantpeach/navigation: ^1
- giantpeach/query: ^1
- giantpeach/route: ^1
- giantpeach/schnapps-framework: ^1
- giantpeach/twiglet: ^1
- guzzlehttp/guzzle: ^7.8
- oscarotero/env: ^2.1
- roots/bedrock-autoloader: ^1.0
- roots/bedrock-disallow-indexing: ^2.0
- roots/wordpress: ^6.5
- roots/wp-config: 1.0.0
- roots/wp-password-bcrypt: 1.1.0
- twig/twig: ^3.6
- vlucas/phpdotenv: ^5.5
- wpackagist-plugin/acf-gravityforms-add-on: ^1.3
- wpackagist-plugin/advanced-custom-fields-font-awesome: ^4.0
- wpackagist-plugin/autodescription: ^5.0.6
- wpackagist-plugin/duplicate-page: ^4.5
- wpackagist-plugin/post-types-order: ^2.2
- wpackagist-plugin/redirection: ^5.4.2
- wpackagist-plugin/wp-mail-smtp: ^4.0.1
- wpackagist-plugin/wp-super-cache: ^1.12.0
- wpackagist-theme/twentytwentythree: ^1.0
- wpengine/advanced-custom-fields-pro: *
Requires (Dev)
- giantpeach/wp-salts: dev-master
- mockery/mockery: ^1.6
- phpunit/phpunit: ^10.5
- roave/security-advisories: dev-latest
- squizlabs/php_codesniffer: ^3.7.1
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()
- Simplifies creation and templating of navigation menus within Wordpress, to avoid using
- 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.
- 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
- 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