feat: add example custom blocks

- add documentation to example-blocks
- php pattern globbing to eliminate need for adding individual blocks
- add globbing to scripts to eliminate need for adding individual blocks
- add plugin lint scripts

.github/workflows/lint.yml

@@ -31,6 +31,9 @@ jobs:
       - name: Install npm dependencies
         run: npm ci
 
+      - name: Install custom plugin npm dependencies
+        run: npm run plugins:install
+
       - name: Lint
         run: npm run lint
         env:

.gitignore

@@ -47,5 +47,7 @@ coverage/
 
 plugins/rollbar/
 
+src/plugins/**/build/
+
 # DB imports/exports
 sql

README.md

@@ -14,10 +14,11 @@ This is a starter to fast-track WordPress websites. It provides a way to skip ma
 | [CSS Class Reference](docs/css.md)              |
 | [Page Templates](docs/page-templates.md)        |
 | [Deployment](docs/deployment.md)                |
+| [Custom Blocks](docs/custom-blocks.md)          |
 | [How to Contribute](docs/contributing.md)       |
 
 ## SparkPress Team
 - **[Kasey Bonifacio](https://github.com/kaseybon)**
 - **[Ricardo Fearing](https://github.com/rfearing)**
 - **[Rob Tarr](https://github.com/robtarr)**
-- **[Philip Zastrow](https://github.com/zastrow/)**
+- **[Philip Zastrow](https://github.com/zastrow/)**

docker-compose.yml

@@ -12,6 +12,7 @@ services:
     volumes:
       - ./uploads:/var/www/html/wp-content/uploads
       - ./theme:/var/www/html/wp-content/themes/sparkpress-theme
+      - ./src/plugins/example-blocks:/var/www/html/wp-content/plugins/example-blocks
       - ./wp-configs/wp-config.php:/var/www/html/wp-config.php
       - ./wp-configs/php.ini:/var/www/html/php.ini
       - ./.env:/var/www/html/.env

docs/custom-blocks.md

@@ -0,0 +1,30 @@
+# Custom Blocks
+
+We have a plugin for custom blocks called `example-blocks`, which lives in `src/plugins`. For the blocks to be available in WordPress, these steps must be taken:
+
+1. Run `npm run plugins:install` to install the plugin's npm dependencies
+1. Run `npm start` for local development (this run's the plugin's `npm start` command)
+1. Activate the "Example Blocks" plugin from the WordPress menu
+
+For production builds, running `npm run build:prod` will also work, outputting production bundles for the blocks.
+
+## Creating a New Custom Block
+
+Follow these steps to create a new custom block and wire it up with the normal development/build processes:
+
+1. Create a new folder at `src/plugins/example-blocks/<block-name>`
+1. Either copy files from another block or manually create these files:
+    - `block.json`: configuration/metadata for the block
+    - `src/index.js`: entry point for the JS bundle
+    - `src/edit.js`: the component used while editing
+    - `src/save.js`: the component rendered on the site
+    - `src/editor.scss`: custom styles for the editor view
+    - `src/style.scss`: custom styles for the block when rendered on the site
+1. Configure the custom block by updating `block.json`, namely the `name`, `title`, `icon`, and `description` fields
+1. Implement the edit function, which will usually be form controls corresponding to attributes that you define in `index.js`
+1. Implement the save function, which will consume the attributes defined in `index.js` and render the block's desired markup
+
+## Useful Resources
+
+- [Create a Block Tutorial](https://developer.wordpress.org/block-editor/getting-started/create-block/)
+- [Component Reference](https://developer.wordpress.org/block-editor/reference-guides/components/)

docs/development.md

@@ -32,6 +32,7 @@
 1. Install [Node][node]
 1. In your terminal, navigate to the repo directory
 1. Run `npm install`, wait for installation of modules
+1. Run `npm run plugins:install` to install dependencies for custom plugins (you will need to activate the plugin from WordPress)
 1. Run `npm start` to build the theme and have a watch task to automatically rerun the build when changes are made.
 
 ## Setting Local Environment Variables

package.json

@@ -7,28 +7,36 @@
     "prestart": "run-p clean node-version",
     "start": "run-p build:dev serve:dev",
     "postserve:dev": "docker-compose down",
-    "clean": "rm -rf theme/",
-    "copy": "mkdir -p ./theme && cp -r ./src/php/* ./theme",
+    "clean": "rm -rf theme/ plugins/example-blocks/",
+    "copy": "run-p copy:*",
+    "copy:php": "mkdir -p ./theme && cp -r ./src/php/* ./theme",
+    "copy:plugins": "mkdir -p ./plugins && cp -r ./src/plugins/* ./plugins",
     "prebuild:dev": "npm run clean",
     "prebuild:prod": "npm run clean",
-    "build:dev": "run-p copy sass watch js:watch",
-    "build:prod": "run-s copy js:prod 'sass -- --style compressed'",
+    "build:dev": "run-p plugins:dev copy:php sass watch js:watch",
+    "build:prod": "run-s plugins:build copy js:prod 'sass -- --style compressed'",
     "serve:dev": "docker-compose up",
     "sass": "sass src/scss/base.scss theme/css/base.css",
     "postsass": "postcss theme/css/base.css --use autoprefixer -r",
     "js:watch": "NODE_ENV=development node esbuild.mjs",
     "js:prod": "node esbuild.mjs",
+    "plugins:install": "cd src/plugins/example-blocks && npm ci",
+    "plugins:dev": "cd src/plugins/example-blocks && npm start",
+    "plugins:build": "cd src/plugins/example-blocks && npm run build",
+    "plugins:format": "cd src/plugins/example-blocks && npm run format",
     "watch": "run-p watch:*",
-    "watch:php": "chokidar \"src/php/**/*\" -c \"npm run copy\"",
+    "watch:php": "chokidar \"src/php/**/*\" -c \"npm run copy:php\"",
     "watch:scss": "chokidar \"src/scss/**/*\" -c \"npm run sass\"",
     "test": "vitest --run",
     "test:watch": "vitest",
     "test:ci": "vitest --run --coverage",
+    "lint:plugins:js": "cd src/plugins/example-blocks && npm run lint:js",
+    "lint:plugins:css": "cd src/plugins/example-blocks && npm run lint:css",
     "lint:js": "eslint src/js",
     "lint:php": "./scripts/run.sh vendor/bin/phpcs --standard=wp-configs/sparkpress-standard.xml --extensions=php src/php -s -n",
     "lint:scss": "stylelint src/scss/**/*.scss src/scss/*.scss --color --formatter verbose",
     "lint:twig": "./scripts/run.sh vendor/bin/twigcs src/php/views",
-    "lint": "run-s lint:*",
+    "lint": "run-s lint:* lint:plugins:*",
     "php:run": "./scripts/run.sh",
     "export-db": "./scripts/export-db.sh",
     "backup-db": "BACKUP=true ./scripts/export-db.sh",

src/plugins/example-blocks/.editorconfig

@@ -0,0 +1,18 @@
+# This file is for unifying the coding style for different editors and IDEs
+# editorconfig.org
+
+# WordPress Coding Standards
+# https://make.wordpress.org/core/handbook/coding-standards/
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = tab
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2

src/plugins/example-blocks/.gitignore

@@ -0,0 +1,30 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Output of `npm pack`
+*.tgz
+
+# Output of `wp-scripts plugin-zip`
+*.zip
+
+# dotenv environment variables file
+.env

src/plugins/example-blocks/.prettierrc

@@ -0,0 +1,14 @@
+{
+	"printWidth": 110,
+	"endOfLine": "lf",
+	"trailingComma": "es5",
+	"tabWidth": 2,
+	"useTabs": true,
+	"semi": true,
+	"singleQuote": true,
+	"quoteProps": "as-needed",
+	"jsxSingleQuote": false,
+	"bracketSpacing": true,
+	"bracketSameLine": false,
+	"arrowParens": "always"
+}

src/plugins/example-blocks/blocks/hello-world/block.json

@@ -0,0 +1,17 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/block.json",
+	"apiVersion": 3,
+	"name": "example-blocks/hello-world",
+	"version": "0.1.0",
+	"title": "Hello World",
+	"category": "example-custom-blocks",
+	"icon": "nametag",
+	"description": "Prints Hello World!",
+	"supports": {
+		"html": false
+	},
+	"textdomain": "example-blocks",
+	"editorScript": "file:./build/index.js",
+	"editorStyle": "file:./build/index.css",
+	"style": "file:./build/style-index.css"
+}

src/plugins/example-blocks/blocks/hello-world/src/edit.js

@@ -0,0 +1,34 @@
+/**
+ * Retrieves the translation of text.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * React hook that is used to mark the block wrapper element.
+ * It provides all the necessary props like the class name.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
+ */
+import { useBlockProps } from '@wordpress/block-editor';
+
+/**
+ * Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
+ * Those files can contain any CSS code that gets applied to the editor.
+ *
+ * @see https://www.npmjs.com/package/@wordpress/scripts#using-css
+ */
+import './editor.scss';
+
+/**
+ * The edit function describes the structure of your block in the context of the
+ * editor. This represents what the editor will render when the block is used.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#edit
+ *
+ * @return {WPElement} Element to render.
+ */
+export default function Edit() {
+	return <p {...useBlockProps()}>{__('Hello World!', 'example-blocks')}</p>;
+}

src/plugins/example-blocks/blocks/hello-world/src/editor.scss

@@ -0,0 +1,10 @@
+/**
+ * The following styles get applied inside the editor only.
+ *
+ * Replace them with your own styles or remove the file completely.
+ */
+
+.wp-block-example-blocks-hello-world {
+
+	/* insert custom styles here */
+}

src/plugins/example-blocks/blocks/hello-world/src/index.js

@@ -0,0 +1,39 @@
+/**
+ * Registers a new block provided a unique name and an object defining its behavior.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
+ */
+import { registerBlockType } from '@wordpress/blocks';
+
+/**
+ * Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
+ * All files containing `style` keyword are bundled together. The code used
+ * gets applied both to the front of your site and to the editor.
+ *
+ * @see https://www.npmjs.com/package/@wordpress/scripts#using-css
+ */
+import './style.scss';
+
+/**
+ * Internal dependencies
+ */
+import Edit from './edit';
+import save from './save';
+import metadata from '../block.json';
+
+/**
+ * Every block starts by registering a new block type definition.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
+ */
+registerBlockType(metadata.name, {
+	/**
+	 * @see ./edit.js
+	 */
+	edit: Edit,
+
+	/**
+	 * @see ./save.js
+	 */
+	save,
+});

src/plugins/example-blocks/blocks/hello-world/src/save.js

@@ -0,0 +1,20 @@
+/**
+ * React hook that is used to mark the block wrapper element.
+ * It provides all the necessary props like the class name.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
+ */
+import { useBlockProps } from '@wordpress/block-editor';
+
+/**
+ * The save function defines the way in which the different attributes should
+ * be combined into the final markup, which is then serialized by the block
+ * editor into `post_content`.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#save
+ *
+ * @return {WPElement} Element to render.
+ */
+export default function save() {
+	return <p {...useBlockProps.save()}>{'Hello World!'}</p>;
+}

src/plugins/example-blocks/blocks/hello-world/src/style.scss

@@ -0,0 +1,12 @@
+/**
+ * The following styles get applied both on the front of your site
+ * and in the editor.
+ *
+ * Replace them with your own styles or remove the file completely.
+ */
+
+.wp-block-example-blocks-hello-world {
+	background-color: #21759b;
+	color: #fff;
+	padding: 2px;
+}

src/plugins/example-blocks/blocks/reverse-string/block.json

@@ -0,0 +1,17 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/block.json",
+	"apiVersion": 3,
+	"name": "example-blocks/reverse-string",
+	"version": "0.1.0",
+	"title": "Reverse String",
+	"category": "example-custom-blocks",
+	"icon": "smiley",
+	"description": "Prints a user-entered string in reverse order.",
+	"supports": {
+		"html": false
+	},
+	"textdomain": "example-blocks",
+	"editorScript": "file:./build/index.js",
+	"editorStyle": "file:./build/index.css",
+	"style": "file:./build/style-index.css"
+}

src/plugins/example-blocks/blocks/reverse-string/src/edit.js

@@ -0,0 +1,39 @@
+import { TextControl } from '@wordpress/components';
+
+/**
+ * React hook that is used to mark the block wrapper element.
+ * It provides all the necessary props like the class name.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
+ */
+import { useBlockProps } from '@wordpress/block-editor';
+
+/**
+ * Lets webpack process CSS, SASS or SCSS files referenced in JavaScript files.
+ * Those files can contain any CSS code that gets applied to the editor.
+ *
+ * @see https://www.npmjs.com/package/@wordpress/scripts#using-css
+ */
+import './editor.scss';
+
+/**
+ * The edit function describes the structure of your block in the context of the
+ * editor. This represents what the editor will render when the block is used.
+ *
+ * @param {Object}   props
+ * @param {Object}   props.attributes
+ * @param {Function} props.setAttributes
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#edit
+ *
+ * @return {WPElement} Element to render.
+ */
+export default function Edit({ attributes, setAttributes }) {
+	const { textToReverse } = attributes;
+	const updateTextToReverse = (newText) => setAttributes({ textToReverse: newText });
+
+	return (
+		<div {...useBlockProps()}>
+			<TextControl label="Text to Reverse" value={textToReverse} onChange={updateTextToReverse} />
+		</div>
+	);
+}

src/plugins/example-blocks/blocks/reverse-string/src/editor.scss

@@ -0,0 +1,13 @@
+/**
+ * The following styles get applied inside the editor only.
+ *
+ * Replace them with your own styles or remove the file completely.
+ */
+
+.wp-block-example-blocks-reverse-string {
+	padding: 1em;
+	box-sizing: border-box;
+	border: none;
+	border-radius: 2px;
+	box-shadow: inset 0 0 0 1px #1e1e1e;
+}