Add initial scaffold block command #96

gziolo · 2017-11-23T14:58:45Z

Related issue: #88.

This PR implements a scaffolding command dedicated to Gutenberg blocks. It's a first iteration which is focused on a very basic static block which can't be edited in Gutenberg. In the follow-up PR we can cover more advanced examples like a dynamic block or server-side rendered block using Post meta.

To use the generated code you need to require php file inside your plugin or theme, depending which option you pick.

You can learn more about writing blocks in this article and in the official documentation.

Example usage

Commands should be executed from the WordPress folder or with --path option.

wp scaffold block my-block --theme

wp scaffold block my-another-block --plugin=my-plugin-name --category=widget

wp scaffold block my-yet-another-block --theme --dashicon=editor-paragraph

Example output

Command: wp scaffold block movie --title="movie block" --theme

wordpress/wp-content/themes/twentyseventeen/blocks/movie.php:

<?php

function movie_enqueue_block_editor_assets() {
	$dir = dirname( __FILE__ );
	$block_js = 'movie/block.js';
	$editor_css = 'movie/editor.css';
	wp_enqueue_script( 'movie-block', plugins_url( $block_js, __FILE__ ), array(
		'wp-blocks',
		'wp-i18n',
		'wp-element',
	), filemtime( "$dir/$block_js" ) );
	wp_enqueue_style( 'movie-block', plugins_url( $editor_css, __FILE__ ), array(
		'wp-blocks',
	), filemtime( "$dir/$editor_css" ) );
}
add_action( 'enqueue_block_editor_assets', 'movie_enqueue_block_editor_assets' );

wordpress/wp-content/themes/twentyseventeen/blocks/movie/block.js:

( function( wp ) {
	var el = wp.element.createElement;
	var __ = wp.i18n.__;

	// Visit https://wordpress.org/gutenberg/handbook/block-api/ to learn about Block API
	wp.blocks.registerBlockType( 'twentyseventeen/movie', {
		title: __( 'Movie block', 'twentyseventeen' ),

		category: 'widgets',

		// Remove to make block editable in HTML mode.
		supportHTML: false,

		edit: function( props ) {
			return el(
				'p',
				{ className: props.className },
				__( 'Replace with your content!', 'twentyseventeen' )
			);
		},

		save: function() {
			return el(
				'p',
				{},
				__( 'Replace with your content!', 'twentyseventeen' )
			);
		}
	} );
} )(
	window.wp
);

wordpress/wp-content/themes/twentyseventeen/blocks/movie/editor.css:

.wp-block-twentyseventeen-movie {
	/* Replace with your styles. */
	background-color: #000;
	color: #fff;
}

Commands that produce errors

wp scaffold block MyBlock

Error: Invalid block slug specified. Block slugs can contain only lowercase alphanumeric characters or dashes, and start with a letter.

wp scaffold block my-block

Error: No plugin or theme selected.

wp scaffold block my-block --category=unknown

Error: Invalid block category specified. Block categories need to match one of the registered values.

wp scaffold block movie --title=Movie --theme=simple-life

Error: Can't find 'simple-life' theme.

wp scaffold block movie --title=Movie --plugin=simple-life

Error: Can't find 'simple-life' plugin.

TODO

Functional tests
Documentation updates

Block examples:

Giphy block by @obenland.
Stars bloc by @pento.

danielbachhuber

👍 Looks like a great start! I've left some inline comments.

danielbachhuber · 2017-11-27T14:28:54Z

src/Scaffold_Command.php

+	 *
+	 * [--theme]
+	 * : Create files in the active theme directory. Specify a theme
+	 * with `--theme=<theme>` to have the file placed in that theme.


Argument descriptions are wordwrapped automatically, so no need to wordwrap here.

danielbachhuber · 2017-11-27T14:31:50Z

src/Scaffold_Command.php

+		$data     = $this->extract_args( $assoc_args, $defaults );
+
+		if ( ! in_array( $data['category'], $registered_categories ) ) {
+			WP_CLI::error( "Invalid block category specified. Block categories need to match one of the registered values." );


This can be handled by adding YAML doc to the argument definition:

[--category=<category>] : The category name to help users browse and discover your block. --- options: - common - etc.

Nice feature. I will use YAML instead 👍

danielbachhuber · 2017-11-27T14:33:24Z

src/Scaffold_Command.php

+	 * @param array $assoc_args
+	 * @return string|null
+	 */
+	private function maybe_extract_dashicon( $assoc_args ) {


I'm not a huge fan of functions that start with maybe_ because it implies their behavior is ambiguous. Can we come up with a better name for it?

Welcome to the club. I followed the existing code: maybe_create_themes_dir and maybe_create_plugins_dir. I will figure out something else. I want to avoid code duplication here.

danielbachhuber · 2017-11-27T14:33:56Z

src/Scaffold_Command.php

+	/**
+	 * Generate the machine name for function declarations.
+	 *
+	 * @param string $slug Slug name to .


Looks like this description is incomplete

danielbachhuber · 2017-11-27T14:34:15Z

src/Scaffold_Command.php

+	 * @return string
+	 */
+	private function generate_machine_name( $slug ) {
+		return preg_replace( '/-/', '_', $slug );


Is there a reason not to use str_replace(), which is more performant?

I used refactor method feature in my IDE and didn't look at the code. You are totally right, I will update.

danielbachhuber · 2017-11-27T14:35:10Z

templates/block-js.mustache

+	var el = wp.element.createElement;
+	var __ = wp.i18n.__;
+
+	// Visit https://wordpress.org/gutenberg/handbook/block-api/ to learn about Block API


Should this be linked to in the wp scaffold block command description?

We should add it there, too.

danielbachhuber · 2017-11-27T14:41:48Z

src/Scaffold_Command.php

+	 * : The dashicon to make it easier to identify your block.
+	 *
+	 * [--category=<category>]
+	 * : The category name to help users browse and discover your block.


Could/should this category impact scaffolded code?

Yes, it is consumed here: https://github.com/wp-cli/scaffold-command/pull/96/files#diff-5384a491183730a8d9db2944d7fcb8d6R13.

danielbachhuber · 2017-11-27T14:42:11Z

src/Scaffold_Command.php

@@ -201,6 +200,106 @@ private function _scaffold( $slug, $assoc_args, $defaults, $subdir, $templates )
 		}
 	}

+	/**
+	 * Generate PHP, JS and CSS code for registering a custom block.
+	 *


Would this benefit from a longer explanation of what a block is, etc.?

danielbachhuber · 2017-11-27T14:43:55Z

templates/block-php.mustache

+		'wp-blocks',
+		'wp-i18n',
+		'wp-element',
+	), time() );


It's probably a bad idea to use time() as the script version in production. If you want this to automatically update when the file is changed, you could use filemtime() to get the modified time for the file and append this instead.

I copied it from one of the examples. Agreed on filemtime :)

danielbachhuber · 2017-11-27T14:44:29Z

templates/block-js.mustache

+			return el(
+				'p',
+				{ className: props.className },
+				__( 'Replace with your content!', '{{textdomain}}' )


Would it be helpful to have a more substantive example?

I think this example is good, maybe we should comment it differently. @mtias @youknowriad, do you have some thoughts on that?

gziolo · 2017-11-27T15:21:39Z

@danielbachhuber for your feedback, I will update PR tomorrow.

obenland · 2017-11-27T16:20:47Z

src/Scaffold_Command.php

+	 *
+	 * [--theme]
+	 * : Create files in the active theme directory. Specify a theme
+	 * with `--theme=<theme>` to have the file placed in that theme.


I'd advocate for not including a theme parameter here. Blocks are content and probably shouldn't stop being supported when you switch themes.

I wasn't sure if include theme option here, but I decided to do it based on the Block API documentation which includes the following:

Blocks are the fundamental element of the Gutenberg editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor.

@mtias, what is your opinion about it?

gziolo · 2017-11-28T12:41:20Z

@danielbachhuber I addressed your comments, added documentation, and functional tests. It's ready for another look.

danielbachhuber · 2017-11-28T13:15:17Z

README.md

+	Success: Created block 'Movie block'.
+
+	Generate PHP code for registering a custom taxonomy.
+


grappler · 2018-01-30T00:43:36Z

templates/block-block-js.mustache

+
+	// Visit https://wordpress.org/gutenberg/handbook/block-api/ to learn about Block API
+	wp.blocks.registerBlockType( '{{namespace}}/{{slug}}', {
+		title: __( '{{title_ucfirst}}', '{{textdomain}}' ),


@gziolo This does not seem to be the correct way of defining the textdomain. https://github.com/WordPress/gutenberg/tree/master/i18n

I don't think there is any proper way of defining the text domain WordPress/gutenberg#4147

This was fixed after this PR got merged in c74032f

Add initial scaffold block command

Add initial scaffold block command

10606cd

danielbachhuber reviewed Nov 27, 2017

View reviewed changes

obenland reviewed Nov 27, 2017

View reviewed changes

gziolo added 4 commits November 28, 2017 10:54

Add improvements for wp scaffold block command

ca5b1ed

Add documentation for wp scaffold block command

d2eef7e

Add functional tests for wp block scaffold

3554992

Update JavaScript template for block scaffolding command

daf30d6

danielbachhuber approved these changes Nov 28, 2017

View reviewed changes

README.md

Success: Created block 'Movie block'.

Generate PHP code for registering a custom taxonomy.

Copy link

Member

danielbachhuber Nov 28, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good.

danielbachhuber added the command:scaffold-block label Nov 28, 2017

danielbachhuber added this to the 1.1 milestone Nov 28, 2017

danielbachhuber changed the title ~~[WIP] Add initial scaffold block command~~ Add initial scaffold block command Nov 28, 2017

danielbachhuber merged commit f174112 into wp-cli:master Nov 28, 2017

gziolo deleted the add/scaffold-block branch November 28, 2017 13:45

swissspidy mentioned this pull request Dec 12, 2017

Gutenberg Integration wearerequired/wp-team-list#46

Closed

gziolo mentioned this pull request Jan 12, 2018

Add a dynamic render template to the block scaffold #108

Closed

grappler reviewed Jan 30, 2018

View reviewed changes

danielbachhuber added a commit that referenced this pull request Nov 18, 2022

Merge pull request #96 from gziolo/add/scaffold-block

48daf76

Add initial scaffold block command

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add initial scaffold block command #96

Add initial scaffold block command #96

gziolo commented Nov 23, 2017 •

edited

Loading

danielbachhuber left a comment

danielbachhuber Nov 27, 2017

danielbachhuber Nov 27, 2017

gziolo Nov 27, 2017

danielbachhuber Nov 27, 2017

gziolo Nov 27, 2017

danielbachhuber Nov 27, 2017

danielbachhuber Nov 27, 2017

gziolo Nov 27, 2017

danielbachhuber Nov 27, 2017

gziolo Nov 27, 2017

danielbachhuber Nov 27, 2017

gziolo Nov 27, 2017

danielbachhuber Nov 27, 2017

gziolo Nov 28, 2017

danielbachhuber Nov 27, 2017

gziolo Nov 27, 2017

danielbachhuber Nov 27, 2017

gziolo Nov 27, 2017 •

edited

Loading

gziolo commented Nov 27, 2017

obenland Nov 27, 2017

gziolo Nov 28, 2017

gziolo commented Nov 28, 2017

danielbachhuber Nov 28, 2017

grappler Jan 30, 2018

schlessera Jan 30, 2018

		Success: Created block 'Movie block'.

		Generate PHP code for registering a custom taxonomy.

Add initial scaffold block command #96

Add initial scaffold block command #96

Conversation

gziolo commented Nov 23, 2017 • edited Loading

Example usage

Example output

Commands that produce errors

TODO

Block examples:

danielbachhuber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo Nov 27, 2017 • edited Loading

Choose a reason for hiding this comment

gziolo commented Nov 27, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Nov 28, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Nov 23, 2017 •

edited

Loading

gziolo Nov 27, 2017 •

edited

Loading