Merge pull request #134 from moderntribe/feature/MOOSE-77/create-bloc…

…k-templates

[MOOSE-77] Block Templates

CHANGELOG.md

@@ -3,6 +3,8 @@
 All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Each changelog entry gets prefixed with the category of the item (Added, Changed, Depreciated, Removed, Fixed, Security).
 
 ## [2024.04]
+- Removed: `example` custom block in favor of custom block generation through `npm run create-block`.
+- Added: Custom block external template (+ documentation) that allows us to quickly create blocks through the command line using `npm run create-block`. [[MOOSE-77]](https://moderntribe.atlassian.net/browse/MOOSE-77)
 - Changed: Remove Gravity Forms as a composer dependency and the respective mtribe.site composer utility. Gravity Forms should be added directly to a project repo when required.
 - Chore: Composer updates including plugins: advanced-custom-fields-pro:6.2.9, duracelltomi-google-tag-manager:1.20.2, limit-login-attempts-reloaded:2.26.8, safe-svg:2.2.4, seo-by-rank-math:1.0.216, user-switching:1.7.3
 - Chore: Update NPM packages, including swapping browser-sync-webpack-plugin to browser-sync-v3-webpack-plugin for correct version support.

dev/templates/block/edit.js.mustache

@@ -0,0 +1,47 @@
+import { __ } from '@wordpress/i18n';
+import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
+import { PanelBody, TextControl } from '@wordpress/components';
+{{#isDynamicVariant}}
+import ServerSideRender from '@wordpress/server-side-render';
+{{/isDynamicVariant}}
+
+import './editor.pcss';
+
+export default function Edit( { attributes, setAttributes, isSelected } ) {
+	const blockProps = useBlockProps();
+
+	const { exampleTextControl } = attributes;
+
+	return (
+		<div { ...blockProps }>
+			{{#isDynamicVariant}}
+			<ServerSideRender block="{{namespace}}/{{slug}}" attributes={ attributes } />
+			{{/isDynamicVariant}}
+			{{#isStaticVariant}}
+			<p>{ __( '{{title}} – hello from the editor!', '{{namespace}}' ) }</p>
+			{ exampleTextControl ? <p>{ exampleTextControl }</p> : '' }
+			{{/isStaticVariant}}
+			{ isSelected && (
+				<InspectorControls>
+					<PanelBody title={ __( 'Block Settings', '{{namespace}}' ) }>
+						<TextControl
+							label={ __( 'Example Text Control', '{{namespace}}' ) }
+							value={ exampleTextControl }
+							help={ __(
+								'Some helpful text describing the text control.',
+								'{{namespace}}'
+							) }
+							placeholder={ __(
+								'Helpful placeholder text',
+								'{{namespace}}'
+							) }
+							onChange={ ( value ) =>
+								setAttributes( { exampleTextControl: value } )
+							}
+						/>
+					</PanelBody>
+				</InspectorControls>
+			) }
+		</div>
+	);
+}

dev/templates/block/editor.pcss.mustache

@@ -0,0 +1,9 @@
+/* -------------------------------------------------------------------------
+ *
+ * Block - {{title}} - Styles - Editor Only
+ *
+ * ------------------------------------------------------------------------- */
+
+{{#isDynamicVariant}}section{{/isDynamicVariant}}.wp-block-{{namespace}}-{{slug}} {
+	border: 1px dotted #f00;
+}

dev/templates/block/index.js.mustache

@@ -0,0 +1,23 @@
+import { registerBlockType } from '@wordpress/blocks';
+
+import './style.pcss';
+
+import Edit from './edit';
+{{#isStaticVariant}}
+import save from './save';
+{{/isStaticVariant}}
+import metadata from './block.json';
+
+registerBlockType( metadata.name, {
+	/**
+	 * @see ./edit.js
+	 */
+	edit: Edit,
+	{{#isStaticVariant}}
+
+	/**
+	 * @see ./save.js
+	 */
+	save,
+	{{/isStaticVariant}}
+} );

dev/templates/block/render.php.mustache

@@ -0,0 +1,12 @@
+{{#isDynamicVariant}}
+<?php declare(strict_types=1);
+
+$example_text_control = $attributes['exampleTextControl']; // @phpstan-ignore-line
+?>
+<section <?php echo get_block_wrapper_attributes(); ?>>
+	<p><?php esc_html_e( '{{title}} – hello from a dynamic block!', '{{namespace}}' ); ?></p>
+	<?php if ( $example_text_control ) : ?>
+		<p><?php echo esc_html( $example_text_control ); ?></p>
+	<?php endif; ?>
+</section>
+{{/isDynamicVariant}}

dev/templates/block/save.js.mustache

@@ -0,0 +1,16 @@
+{{#isStaticVariant}}
+import { useBlockProps } from '@wordpress/block-editor';
+
+export default function save( { attributes } ) {
+	const blockProps = useBlockProps.save();
+
+	const { exampleTextControl } = attributes;
+
+	return (
+		<section { ...blockProps }>
+			<p>{ '{{title}} – hello from the saved content!' }</p>
+			{ exampleTextControl ? <p>{ exampleTextControl }</p> : '' }
+		</section>
+	);
+}
+{{/isStaticVariant}}

dev/templates/block/style.pcss.mustache

@@ -0,0 +1,11 @@
+/* -------------------------------------------------------------------------
+ *
+ * Block - {{title}} - Styles - FE / Editor
+ *
+ * ------------------------------------------------------------------------- */
+
+.wp-block-{{namespace}}-{{slug}} {
+	background-color: #21759b;
+	color: #fff;
+	padding: 2px;
+}

dev/templates/block/view.js.mustache

@@ -0,0 +1,25 @@
+/**
+ * Use this file for JavaScript code that you want to run in the front-end
+ * on posts/pages that contain this block.
+ *
+ * When this file is defined as the value of the `viewScript` property
+ * in `block.json` it will be enqueued on the front end of the site.
+ *
+ * Example:
+ *
+ * ```js
+ * {
+ *   "viewScript": "file:./view.js"
+ * }
+ * ```
+ *
+ * If you're not making any changes to this file because your block doesn't need any
+ * JavaScript running in the front-end, then you should delete this file and remove
+ * the `viewScript` property from `block.json`.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#view-script
+ */
+
+/* eslint-disable no-console */
+console.log( 'Hello World! (from {{namespace}}-{{slug}} block)' );
+/* eslint-enable no-console */

dev/templates/index.js

@@ -0,0 +1,30 @@
+const { join } = require( 'path' );
+
+module.exports = {
+	blockTemplatesPath: join( __dirname, 'block' ),
+	defaultValues: {
+		attributes: {
+			exampleTextControl: {
+				type: 'string',
+				default: '',
+			},
+		},
+		dashicon: 'block-default',
+		supports: {
+			html: false,
+			align: [ 'wide', 'grid', 'full' ],
+			spacing: {
+				margin: true,
+				padding: true,
+			},
+		},
+		textdomain: 'tribe',
+		viewScript: 'file:./view.js',
+	},
+	variants: {
+		static: {},
+		dynamic: {
+			render: 'file:./render.php',
+		},
+	},
+};

dev/templates/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "tribe-block-templates",
+  "version": "1.0.0",
+  "description": "Custom block templates for the WP create-block script to use",
+	"author": "Modern Tribe <[email protected]>",
+	"license": "GPL-2.0-or-later",
+	"keywords": [],
+	"homepage": "https://github.com/moderntribe/moose#readme",
+	"repository": "https://github.com/moderntribe/moose",
+	"bugs": {
+		"email": "[email protected]"
+	},
+	"main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

docs/block-templates.md

@@ -0,0 +1,25 @@
+# Block Templates
+
+Last Updated: 04/23/24
+
+Currently we support creating static and dynamic custom blocks. Generated custom blocks ultimately live in the core theme under `./blocks/tribe`.
+
+Please see the WordPress documentation on [external block templates here](https://developer.wordpress.org/news/2024/04/16/creating-an-external-project-template-for-create-block/).
+
+## Usage
+
+In your command line tool, you can run `npm run create-block`. This will trigger the create block tool. Once within this tool, follow the prompts to complete creating your block 
+
+- Steps to create a custom block: http://p.tri.be/i/Iaz9Ym
+	1. Choose the template variant (static or dynamic)
+	2. Enter the slug for the block
+	3. Enter the name for the block
+	4. Enter a short description of the block
+	5. Pick a [dashicon](https://developer.wordpress.org/resource/dashicons/) to assign to the block
+	6. Choose a category to assign to your block
+- Created block markup (static variant): http://p.tri.be/i/0HRhUd
+
+## Gotchas
+
+- Because the `create-block` script inherits the code that creates the "plugin" version of a block, it also inherits the code where the `textdomain` property in the `block.json` file is automatically set to the defined block slug. This only applies to the `block.json` file, as we use the `namespace` in the template files to get around this. Please remember to update the `textdomain` property in the `block.json` file once your block gets generated.
+- Once the block is created, don't forget to add the block slug to the block definers `TYPES` array in the core plugin under `./src/Blocks/Blocks_Definer.php`.

package.json

@@ -24,7 +24,8 @@
 	"config": {
 		"coreThemeDir": "./wp-content/themes/core",
 		"corePluginDir": "./wp-content/plugins/core",
-		"coreThemeBlocksDir": "./wp-content/themes/core/blocks"
+		"coreThemeBlocksDir": "./wp-content/themes/core/blocks",
+		"coreBlockTemplatesDir": "../../../../../dev/templates"
 	},
 	"devDependencies": {
 		"@csstools/postcss-global-data": "^2.1.0",
@@ -55,7 +56,7 @@
 		"lint:configs": "wp-scripts lint-js \"./*.js\"",
 		"lint:configs:fix": "wp-scripts lint-js \"./*.js\" --fix",
 		"lint:pkg-json": "wp-scripts lint-pkg-json",
-		"create-block": "cd \"$npm_package_config_coreThemeBlocksDir/tribe\" && npx @wordpress/create-block --no-plugin --namespace tribe",
+		"create-block": "cd \"$npm_package_config_coreThemeBlocksDir/tribe\" && npx @wordpress/create-block --no-plugin --namespace tribe --template $npm_package_config_coreBlockTemplatesDir",
 		"packages-update": "wp-scripts packages-update",
 		"check-engines": "wp-scripts check-engines",
 		"check-licenses": "wp-scripts check-licenses",