Merge pull request #25 from WebDevStudios/feature/WDSBT-20-custom-blocks

Feature/WDSBT-20 Custom block build process

.eslintignore

@@ -1,3 +1,4 @@
+blocks
 build
 node_modules
 vendor

.gitignore

@@ -23,6 +23,7 @@ vendor/
 
 # theme
 build/
+blocks/
 
 #tests
 pa11y-ci-report/

.markdownlintignore

@@ -1,3 +1,4 @@
+blocks
 build
 node_modules
 vendor

.prettierignore

@@ -1,5 +1,7 @@
+blocks/
 build/
 node_modules/
 vendor/
 style.css
 README.md
+acf-json/

.stylelintignore

@@ -1,3 +1,4 @@
+blocks/
 build/
 vendor/
 node_modules/

README.md

@@ -17,6 +17,7 @@
 - [Getting Started](#getting-started)
 - [Development](#development)
  - [NPM Scripts](#npm-scripts)
+- [Creating Custom Blocks](#creating-blocks)
 - [Customizations](#customizations)
  - [Implementation](#implementation)
  - [Mixins](#mixins)
@@ -205,6 +206,7 @@ npm run setup
 |-------|---------|-------------|
 | 🌐 | `npm run a11y` | Run accessibility tests using Pa11y-CI. |
 | 🛠️ | `npm run build` | Build the theme using `wp-scripts`. |
+| 🔨 | `npm run create-block` | Create a custom block with Webpack and @wordpress/create-block. |
 | 📝 | `npm run format` | Format files using `wp-scripts` and `composer`. |
 | 🔍 | `npm run lint` | Run all linting scripts. |
 | 🎨 | `npm run lint:css` | Lint CSS files using `wp-scripts`. |
@@ -218,6 +220,30 @@ npm run setup
 | ▶️ | `npm run start` | Start the development server using `wp-scripts`. |
 
 
+[🔝 Back to Top](#wds-bt)
+***
+
+## Creating Blocks
+
+1. Run the Block Creation Script
+ Navigate to your project root in the terminal and run the following command to create a new block:
+
+```bash
+npm run create-block
+```
+
+Follow the prompts to configure your new block. The script will scaffold a new block structure inside assets/blocks/.
+
+2. Build your block
+ After editing and configuring your block, build your project to compile assets using webpack:
+
+```bash
+npm run build
+```
+This will process JavaScript, SCSS, optimize images, and generate necessary files in the build/ directory and custom blocks will have files generated in the blocks/ directory.
+
+
+
 [🔝 Back to Top](#wds-bt)
 ***
 
@@ -245,13 +271,13 @@ npm run setup
 </details>
 
 <details closed>
-<summary><b>Overriding/Customizing Core Block Styles</b></summary>
+<summary><b>Overriding/Customizing Block Styles</b></summary>
 
-1. Navigate to the `assets/scss/blocks/core` directory within your theme.
+1. Navigate to the `assets/scss/blocks/` directory within your theme. If overriding a core block style, use the `core` folder, if overriding a block from a plugin use the `custom` folder.
 
-2. Create an SCSS file with the exact filename as the block name you want to customize. This file will house your custom styles for that specific core block.
+2. Create an SCSS file with the exact filename as the block name you want to customize. This file will house your custom styles for that specific block.
 
-3. Files within the `assets/scss/blocks/core` directory are automatically enqueued, simplifying the integration of your custom styles into the WordPress block editor. Do not import these files into the main `index.scss`
+3. Files within the `assets/scss/blocks/core/` directory are automatically enqueued, simplifying the integration of your custom styles into the WordPress block editor. Do not import these files into the main `index.scss`
 
 4. After adding your custom SCSS file, run the following command to compile and apply your changes:
 

assets/scss/editor.scss

@@ -0,0 +1 @@
+/* -- Editor Stykes -- */

babel.config.json

@@ -0,0 +1,3 @@
+{
+ "presets": ["@babel/preset-env", "@babel/preset-react"]
+}

composer.json

@@ -25,14 +25,15 @@
  "composer/installers": "^2.2.0"
  },
  "require-dev": {
+ "php": ">=8.0",
  "dealerdirect/phpcodesniffer-composer-installer": "^1.0.0",
  "phpcompatibility/phpcompatibility-wp": "^2.1.4",
  "squizlabs/php_codesniffer": "^3.10.1",
  "wp-cli/wp-cli-bundle": "^2.10.0",
  "wp-coding-standards/wpcs": "^3.1.0"
  },
  "scripts": {
- "fix": "./vendor/bin/phpcbf --report=summary,source",
- "lint": "./vendor/bin/phpcs --report=summary,source"
+ "phpcs": "./vendor/bin/phpcs --report=full,source",
+ "phpcs-fix": "./vendor/bin/phpcbf --report=summary,source"
  }
 }

inc/block-template/README.md

@@ -0,0 +1,26 @@
+# WDS Block Template
+
+This template is configured to generate a block that is ready for block registration using the [`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) tool.
+
+## Usage
+
+Run the following in the terminal of your choice:
+
+`npx @wordpress/create-block --template ../../inc/block-template --no-plugin`
+
+
+## Structure
+
+Once the command has completed, the following structure will be created:
+
+``` text
+📁src
+└── 📁blocks
+ └── 📁{example-block}
+ └── block.json
+ └── edit.js
+ └── editor.scss
+ └── index.js
+ └── render.php
+ └── style.scss
+```

inc/block-template/block/edit.js.mustache

@@ -0,0 +1,22 @@
+/**
+ * WordPress Dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { useBlockProps } from '@wordpress/block-editor';
+
+/**
+ * Internal Dependencies
+ */
+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
+ */
+export default function Edit() {
+ return (
+ <p {...useBlockProps()}>{__('{{title}} – hello from the editor!', '{{textdomain}}')}</p>
+ );
+}

inc/block-template/block/editor.scss.mustache

@@ -0,0 +1,9 @@
+/**
+ * The following styles get applied inside the editor only.
+ *
+ * Replace them with your own styles or remove the file completely.
+ */
+
+.wp-block-{{namespace}}-{{slug}} {
+ border: 1px dotted var(--wp--preset--color--grey-400);
+}

inc/block-template/block/index.js.mustache

@@ -0,0 +1,33 @@
+/**
+ * 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 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,
+});

inc/block-template/block/render.php.mustache

@@ -0,0 +1,35 @@
+<?php
+/**
+ * PHP file to use when rendering the block type on the server to show on the front end.
+ *
+ * The following variables are exposed to the file:
+ * $attributes (array): The block attributes.
+ * $content (string): The block default content.
+ * $block (WP_Block): The block instance.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md#render
+ */
+
+{{#isInteractiveVariant}}
+// Define some global state
+wp_interactivity_state(
+ '{{slug}}',
+ array()
+);
+
+// Define some context.
+$context = array();
+?>
+<p <?php echo wp_kses_data( get_block_wrapper_attributes() ); ?>
+ data-wp-interactive="{{slug}}"
+ <?php echo wp_interactivity_data_wp_context( $context ); ?>
+>
+ <?php esc_html_e( '{{title}} – hello from an interactive block!', '{{textdomain}}' ); ?>
+</p>
+{{/isInteractiveVariant}}
+{{#isDynamicVariant}}
+?>
+<p <?php echo wp_kses_data( get_block_wrapper_attributes() ); ?>>
+ <?php esc_html_e( '{{title}} – hello from a dynamic block!', '{{textdomain}}' ); ?>
+</p>
+{{/isDynamicVariant}}

inc/block-template/block/style.scss.mustache

@@ -0,0 +1,10 @@
+/**
+ * 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-{{namespace}}-{{slug}} {
+ border: 1px dotted var(--wp--preset--color--grey-400);
+}

inc/block-template/block/view.js.mustache

@@ -0,0 +1,12 @@
+{{#isInteractiveVariant}}
+/**
+ * WordPress dependencies
+ */
+import { store } from '@wordpress/interactivity';
+
+store( '{{slug}}', {
+ state: {},
+ actions: {},
+ callbacks: {},
+} );
+{{/isInteractiveVariant}}

inc/block-template/index.js

@@ -0,0 +1,43 @@
+/**
+ * Dependencies
+ */
+const { join } = require('path');
+
+module.exports = {
+ defaultValues: {
+ transformer: (view) => {
+ const {
+ variantVars: { isInteractiveVariant },
+ } = view;
+ return {
+ ...view,
+ requiresAtLeast: isInteractiveVariant ? '6.5' : '6.1',
+ };
+ },
+ author: 'WebDevStudios',
+ category: 'wds-blocks',
+ dashicon: 'pets',
+ description: 'A custom block created by the create-block for the theme',
+ namespace: 'wdsbt',
+ render: 'file:./render.php',
+ version: '1.0.0',
+ customPackageJSON: {
+ prettier: '@wordpress/prettier-config',
+ },
+ },
+ variants: {
+ dynamic: {},
+ interactive: {
+ viewScriptModule: 'file:./view.js',
+ customScripts: {
+ build: 'wp-scripts build --experimental-modules',
+ start: 'wp-scripts start --experimental-modules',
+ },
+ supports: {
+ interactive: true,
+ },
+ },
+ },
+ pluginTemplatesPath: join(__dirname, 'plugin'),
+ blockTemplatesPath: join(__dirname, 'block'),
+};

inc/block-template/plugin/$slug.php.mustache

@@ -0,0 +1,49 @@
+<?php
+/**
+ * Plugin Name: {{title}}
+{{#pluginURI}}
+ * Plugin URI: {{{pluginURI}}}
+{{/pluginURI}}
+{{#description}}
+ * Description: {{description}}
+{{/description}}
+ * Requires at least: {{requiresAtLeast}}
+ * Requires PHP: 7.0
+ * Version: {{version}}
+{{#author}}
+ * Author: {{author}}
+{{/author}}
+{{#license}}
+ * License: {{license}}
+{{/license}}
+{{#licenseURI}}
+ * License URI: {{{licenseURI}}}
+{{/licenseURI}}
+ * Text Domain: {{textdomain}}
+{{#domainPath}}
+ * Domain Path: {{{domainPath}}}
+{{/domainPath}}
+{{#updateURI}}
+ * Update URI: {{{updateURI}}}
+{{/updateURI}}
+ *
+ * @package {{slugPascalCase}}
+ */
+
+namespace {{slugPascalCase}};
+
+if ( ! defined( 'ABSPATH' ) ) {
+ exit; // Exit if accessed directly.
+}
+
+/**
+ * Registers the block using the metadata loaded from the `block.json` file.
+ * Behind the scenes, it registers also all assets so they can be enqueued
+ * through the block editor in the corresponding context.
+ *
+ * @see https://developer.wordpress.org/reference/functions/register_block_type/
+ */
+function {{slugSnakeCase}}_block_init() {
+ register_block_type_from_metadata( __DIR__ . '/build' );
+}
+add_action( 'init', __NAMESPACE__ . '{{slugSnakeCase}}_block_init' );