Add a new create-block template for the block development quick start guide

docs/manifest.json

@@ -1535,6 +1535,12 @@
 		"markdown_source": "../packages/create-block-interactive-template/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/create-block-quick-start-template",
+		"slug": "packages-create-block-quick-start-template",
+		"markdown_source": "../packages/create-block-quick-start-template/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/create-block-tutorial-template",
 		"slug": "packages-create-block-tutorial-template",

packages/create-block-quick-start-template/.npmrc

@@ -0,0 +1 @@
+package-lock=false

packages/create-block-quick-start-template/CHANGELOG.md

@@ -0,0 +1,3 @@
+<!-- Learn how to maintain this file at https://github.com/WordPress/gutenberg/tree/HEAD/packages#maintaining-changelogs. -->
+
+## Unreleased

packages/create-block-quick-start-template/README.md

@@ -0,0 +1,21 @@
+# Create Block Quick Start Template
+
+This is a template for [`@wordpress/create-block`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/create-block/README.md) that creates an example "Copyright Date" block. This block is used in the official WordPress block development [Quick Start Guide](https://developer.wordpress.org/block-editor/getting-started/block-development-quick-start-guide).
+
+## Usage
+
+This block template can be used by running the following command:
+
+```bash
+npx  @wordpress/create-block --template @wordpress/create-block-quick-start-template
+```
+
+Use the default options when prompted in the terminal.
+
+## Contributing to this package
+
+This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.
+
+To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
+
+<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/create-block-quick-start-template/block-templates/edit.js.mustache

@@ -0,0 +1,107 @@
+/**
+ * Retrieves the translation of text.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Imports the InspectorControls component, which is used to wrap
+ * the block's custom controls that will appear in in the Settings
+ * Sidebar when the block is selected.
+ * 
+ * Also imports the 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/#inspectorcontrols
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops
+ */
+import { InspectorControls, useBlockProps } from '@wordpress/block-editor';
+
+/**
+ * Imports the necessary components that will be used to create
+ * the user interface for the block's settings.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/components/panel/#panelbody
+ * @see https://developer.wordpress.org/block-editor/reference-guides/components/text-control/
+ * @see https://developer.wordpress.org/block-editor/reference-guides/components/toggle-control/
+ */
+import { PanelBody, TextControl, ToggleControl } from '@wordpress/components';
+
+/**
+ * Imports the useEffect React Hook. This is used to set an attribute when the
+ * block is loaded in the Editor.
+ *
+ * @see https://react.dev/reference/react/useEffect
+ */
+import { useEffect } from 'react';
+
+/**
+ * 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
+ *
+ * @param {Object}   props               Properties passed to the function.
+ * @param {Object}   props.attributes    Available block attributes.
+ * @param {Function} props.setAttributes Function that updates individual attributes.
+ *
+ * @return {Element} Element to render.
+ */
+export default function Edit( { attributes, setAttributes } ) {
+	const { fallbackCurrentYear, showStartingYear, startingYear } = attributes;
+
+	// Get the current year and make sure it's a string.
+	const currentYear = new Date().getFullYear().toString();
+
+	// When the block loads, set the fallbackCurrentYear attribute to the
+	// current year if it's not already set.
+	useEffect( () => {
+		if ( currentYear !== fallbackCurrentYear ) {
+			setAttributes( { fallbackCurrentYear: currentYear } );
+		}
+	}, [ currentYear, fallbackCurrentYear, setAttributes ] );
+
+	let displayDate;
+
+	// Display the starting year as well if supplied by the user.
+	if ( showStartingYear && startingYear ) {
+		displayDate = startingYear + '–' + currentYear;
+	} else {
+		displayDate = currentYear;
+	}
+
+	return (
+		<>
+			<InspectorControls>
+				<PanelBody title={ __( 'Settings', '{{textdomain}}' ) }>
+					<ToggleControl
+						checked={ showStartingYear }
+						label={ __(
+							'Show starting year',
+							'{{textdomain}}'
+						) }
+						onChange={ () =>
+							setAttributes( {
+								showStartingYear: ! showStartingYear,
+							} )
+						}
+					/>
+					{ showStartingYear && (
+						<TextControl
+							label={ __(
+								'Starting year',
+								'{{textdomain}}'
+							) }
+							value={ startingYear }
+							onChange={ ( value ) =>
+								setAttributes( { startingYear: value } )
+							}
+						/>
+					) }
+				</PanelBody>
+			</InspectorControls>
+			<p { ...useBlockProps() }>© { displayDate }</p>
+		</>
+	);
+}

packages/create-block-quick-start-template/block-templates/index.js.mustache

@@ -0,0 +1,32 @@
+/**
+ * Registers a new block provided a unique name and an object defining its behavior.
+ *
+ * @see https://developer.wordpress.org/block-editor/developers/block-api/#registering-a-block
+ */
+import { registerBlockType } from '@wordpress/blocks';
+
+/**
+ * Imports the calendar icon, which will be used for the block icon.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-icons/
+ */
+import { calendar } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import Edit from './edit';
+import save from './save';
+import metadata from './block.json';
+
+registerBlockType( metadata.name, {
+	icon: calendar,
+	/**
+	 * @see ./edit.js
+	 */
+	edit: Edit,
+	/**
+	 * @see ./save.js
+	 */
+	save,
+} );

packages/create-block-quick-start-template/block-templates/render.php.mustache

@@ -0,0 +1,33 @@
+<?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
+ */
+
+// Get the current year.
+$current_year = date( "Y" );
+
+// Determine which content to display.
+if ( isset( $attributes['fallbackCurrentYear'] ) && $attributes['fallbackCurrentYear'] === $current_year ) {
+
+	// The current year is the same as the fallback, so use the block content saved in the database (by the save.js function).
+	$block_content = $content;
+} else {
+
+	// The current year is different from the fallback, so render the updated block content.
+	if ( ! empty( $attributes['startingYear'] ) && ! empty( $attributes['showStartingYear'] ) ) {
+		$display_date = $attributes['startingYear'] . '–' . $current_year;
+	} else {
+		$display_date = $current_year;
+	}
+
+	$block_content = '<p ' . get_block_wrapper_attributes() . '>© ' . esc_html( $display_date ) . '</p>';
+}
+
+echo wp_kses_post( $block_content );

packages/create-block-quick-start-template/block-templates/save.js.mustache

@@ -0,0 +1,41 @@
+/**
+ * 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
+ *
+ * @param {Object} props            Properties passed to the function.
+ * @param {Object} props.attributes Available block attributes.
+ *
+ * @return {Element} Element to render.
+ */
+export default function save( { attributes } ) {
+	const { fallbackCurrentYear, showStartingYear, startingYear } = attributes;
+
+	// If there is no fallbackCurrentYear, which could happen if the block
+	// is loaded from a template/pattern, return null. In this case, block
+	// rendering will be handled by the render.php file.
+	if ( ! fallbackCurrentYear ) {
+		return null;
+	}
+
+	let displayDate;
+
+	// Display the starting year as well if supplied by the user.
+	if ( showStartingYear && startingYear ) {
+		displayDate = startingYear + '–' + fallbackCurrentYear;
+	} else {
+		displayDate = fallbackCurrentYear;
+	}
+
+	return <p { ...useBlockProps.save() }>© { displayDate }</p>;
+}

packages/create-block-quick-start-template/index.js

@@ -0,0 +1,41 @@
+/**
+ * External dependencies
+ */
+const { join } = require( 'path' );
+
+module.exports = {
+	defaultValues: {
+		slug: 'copyright-date-block',
+		title: 'Copyright Date',
+		description:
+			"Display your site's copyright date. (Quick Start Example)",
+		npmDependencies: [ '@wordpress/icons' ],
+		attributes: {
+			fallbackCurrentYear: {
+				type: 'string',
+			},
+			showStartingYear: {
+				type: 'boolean',
+			},
+			startingYear: {
+				type: 'string',
+			},
+		},
+		supports: {
+			color: {
+				background: false,
+				text: true,
+			},
+			html: false,
+			typography: {
+				fontSize: true,
+			},
+		},
+		editorScript: 'file:./index.js',
+		render: 'file:./render.php',
+		example: {},
+		wpEnv: true,
+	},
+	pluginTemplatesPath: join( __dirname, 'plugin-templates' ),
+	blockTemplatesPath: join( __dirname, 'block-templates' ),
+};

packages/create-block-quick-start-template/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@wordpress/create-block-quick-start-template",
+	"version": "1.0.0",
+	"description": "This is a template for @wordpress/create-block that creates an example 'Copyright Date' block. This block is used in the official WordPress block development Quick Start Guide.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"create block",
+		"block template",
+		"quick start"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/docs/getting-started/block-development-quick-start-guide",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/create-block-quick-start-template"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

packages/create-block-quick-start-template/plugin-templates/$slug.php.mustache

@@ -0,0 +1,43 @@
+<?php
+/**
+ * Plugin Name:       {{title}}
+{{#pluginURI}}
+ * Plugin URI:        {{{pluginURI}}}
+{{/pluginURI}}
+{{#description}}
+ * Description:       {{description}}
+{{/description}}
+ * Version:           {{version}}
+ * Requires at least: 6.2
+ * Requires PHP:      7.0
+{{#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           {{namespace}}
+ */
+
+/**
+ * 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 {{namespaceSnakeCase}}_{{slugSnakeCase}}_init() {
+	register_block_type( __DIR__ . '/build' );
+}
+add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_init' );