Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 9 commits into from
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions packages/create-block-quick-start-template/.npmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
package-lock=false
3 changes: 3 additions & 0 deletions packages/create-block-quick-start-template/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<!-- Learn how to maintain this file at https://github.com/WordPress/gutenberg/tree/HEAD/packages#maintaining-changelogs. -->

## Unreleased
21 changes: 21 additions & 0 deletions packages/create-block-quick-start-template/README.md
Original file line number Diff line number Diff line change
@@ -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>
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Interactive Block

> **Warning**
> **This block requires Gutenberg 16.2 or superior to work**. The Interactivity API is, at the moment, not part of WordPress Core as it is still very experimental, and very likely to change.

> **Note**
> This block uses the API shared at [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/).

{{#isBasicVariant}}
ndiego marked this conversation as resolved.
Show resolved Hide resolved
This block has been created with the `create-block-interactive-template` and shows a basic structure of an interactive block that uses the Interactivity API.
{{/isBasicVariant}}

Check the following resources for more info about the Interactivity API:
- [`@wordpress/interactivity` package](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/README.md)
- [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/)
- [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in Gutenberg repo discussions
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
/**
* 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';

/**
* 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.
*
* @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#inspectoradvancedcontrols
*/
import { InspectorControls } 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';

/**
* 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 { showStartingYear, startingYear } = attributes;

// Get the current year.
const currentYear = new Date().getFullYear();
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', 'copyright-date-block' ) }>
ndiego marked this conversation as resolved.
Show resolved Hide resolved
<ToggleControl
checked={ showStartingYear }
label={ __(
'Show starting year',
'copyright-date-block'
) }
onChange={ () =>
setAttributes( {
showStartingYear: ! showStartingYear,
} )
}
/>
{ showStartingYear && (
<TextControl
label={ __(
'Starting year',
'copyright-date-block'
) }
value={ startingYear }
onChange={ ( year ) =>
setAttributes( { startingYear: year } )
}
/>
) }
</PanelBody>
</InspectorControls>
<p { ...useBlockProps() }>© { displayDate }</p>
</>
);
}
Original file line number Diff line number Diff line change
@@ -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: Save,
} );
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
<?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" );

// Get the block's attribute values, if they exist.
$starting_year = isset( $attributes['startingYear'] )
? $attributes['startingYear']
: false;
$show_starting_year = isset( $attributes['showStartingYear'] )
? $attributes['showStartingYear']
: false;

// Set the display date.
if ( $starting_year && $show_starting_year ) {
$display_date = $starting_year . '–' . $current_year;
ndiego marked this conversation as resolved.
Show resolved Hide resolved
} else {
$display_date = $current_year;
}

?>
<p <?php echo get_block_wrapper_attributes(); ?>>
© <?php echo esc_html( $display_date ); ?>
</p>
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
/**
* 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 } ) {
ndiego marked this conversation as resolved.
Show resolved Hide resolved
const { showStartingYear, startingYear } = attributes;

// Get the current year.
const currentYear = new Date().getFullYear();
gziolo marked this conversation as resolved.
Show resolved Hide resolved
let displayDate;

// Display the starting year as well if supplied by the user.
if ( showStartingYear && startingYear ) {
displayDate = startingYear + '–' + currentYear;
} else {
displayDate = currentYear;
}

return <p { ...useBlockProps.save() }>© { displayDate }</p>;
}
38 changes: 38 additions & 0 deletions packages/create-block-quick-start-template/index.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
/**
* 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: {
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' ),
};
25 changes: 25 additions & 0 deletions packages/create-block-quick-start-template/package.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
Original file line number Diff line number Diff line change
@@ -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' );
Loading
Loading