@wordpress/create-block 4.4.0 → 4.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +61 -65
- package/lib/init-block.js +2 -0
- package/lib/scaffold.js +2 -0
- package/lib/templates/block/{template.php.mustache → render.php.mustache} +1 -1
- package/lib/templates/es5/$slug.php.mustache +2 -22
- package/lib/templates/es5/index.js.mustache +0 -47
- package/lib/templates/es5/readme.txt.mustache +1 -1
- package/lib/templates/es5/{template.php.mustache → render.php.mustache} +1 -1
- package/lib/templates/plugin/$slug.php.mustache +1 -28
- package/lib/templates/plugin/readme.txt.mustache +1 -1
- package/lib/templates.js +8 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,18 +1,26 @@
|
|
|
1
1
|
# Create Block
|
|
2
2
|
|
|
3
|
-
Create Block is an officially supported tool for scaffolding WordPress
|
|
3
|
+
Create Block is an **officially supported tool for scaffolding a WordPress plugin that registers a block**. It generates PHP, JS, CSS code, and everything you need to start the project. It also integrates a modern build setup with no configuration.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
_It is largely inspired by [create-react-app](https://create-react-app.dev/docs/getting-started). Major kudos to [@gaearon](https://github.com/gaearon), the whole Facebook team, and the React community._
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
> **Blocks are the fundamental elements of modern WordPress sites**. Introduced in [WordPress 5.0](https://wordpress.org/news/2018/12/bebo/), they allow [page and post builder-like functionality](https://wordpress.org/gutenberg/) to every up-to-date WordPress website.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
> _Learn more about the [Block API at the Gutenberg HandBook](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/)._
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Quick start](#quick-start)
|
|
14
|
+
- [Usage](#usage)
|
|
15
|
+
- [Interactive Mode](#interactive-mode)
|
|
16
|
+
- [`slug`](#slug)
|
|
17
|
+
- [`options`](#options)
|
|
18
|
+
- [Available Commands](#available-commands)
|
|
19
|
+
- [External Project Templates](#external-project-templates)
|
|
20
|
+
- [Contributing to this package](#contributing-to-this-package)
|
|
12
21
|
|
|
13
|
-
## Quick start
|
|
14
22
|
|
|
15
|
-
|
|
23
|
+
## Quick start
|
|
16
24
|
|
|
17
25
|
```bash
|
|
18
26
|
$ npx @wordpress/create-block todo-list
|
|
@@ -20,15 +28,17 @@ $ cd todo-list
|
|
|
20
28
|
$ npm start
|
|
21
29
|
```
|
|
22
30
|
|
|
31
|
+
The `slug` provided (`todo-list` in the example) defines the folder name for the scaffolded plugin and the internal block name. The WordPress plugin generated must [be installed manually](https://wordpress.org/support/article/managing-plugins/#manual-plugin-installation).
|
|
32
|
+
|
|
33
|
+
|
|
23
34
|
_(requires `node` version `14.0.0` or above, and `npm` version `6.14.4` or above)_
|
|
24
35
|
|
|
25
|
-
It creates a WordPress plugin that you need to [install manually](https://wordpress.org/support/article/managing-plugins/#manual-plugin-installation).
|
|
26
36
|
|
|
27
|
-
[Watch a video introduction to create-block on Learn.wordpress.org](https://learn.wordpress.org/tutorial/using-the-create-block-tool/)
|
|
37
|
+
> [Watch a video introduction to create-block on Learn.wordpress.org](https://learn.wordpress.org/tutorial/using-the-create-block-tool/)
|
|
28
38
|
|
|
29
39
|
## Usage
|
|
30
40
|
|
|
31
|
-
The
|
|
41
|
+
The `create-block` command generates a project with PHP, JS, and CSS code for registering a block with a WordPress plugin.
|
|
32
42
|
|
|
33
43
|
```bash
|
|
34
44
|
$ npx @wordpress/create-block [options] [slug]
|
|
@@ -36,9 +46,28 @@ $ npx @wordpress/create-block [options] [slug]
|
|
|
36
46
|
|
|
37
47
|
|
|
38
48
|
|
|
39
|
-
|
|
49
|
+
> The name for a block is a unique string that identifies a block. Block Names are structured as `namespace`/`slug`, where namespace is the name of your plugin or theme.
|
|
50
|
+
|
|
51
|
+
> In most cases, we recommended pairing blocks with WordPress plugins rather than themes, because only using plugin ensures that all blocks still work when your theme changes.
|
|
52
|
+
|
|
53
|
+
### Interactive Mode
|
|
54
|
+
|
|
55
|
+
When no `slug` is provided, the script will run in interactive mode and will start prompting for the input required (`slug`, title, namespace...) to scaffold the project.
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
### `slug`
|
|
59
|
+
|
|
60
|
+
The use of `slug` is optional.
|
|
61
|
+
|
|
62
|
+
When provided it triggers the _quick mode_, where this `slug` is used:
|
|
63
|
+
- as the block slug (required for its identification)
|
|
64
|
+
- as the output location (folder name) for scaffolded files
|
|
65
|
+
- as the name of the WordPress plugin.
|
|
66
|
+
|
|
67
|
+
The rest of the configuration is set to all default values unless overridden with some options listed below.
|
|
68
|
+
|
|
69
|
+
### `options`
|
|
40
70
|
|
|
41
|
-
Options:
|
|
42
71
|
|
|
43
72
|
```bash
|
|
44
73
|
-V, --version output the version number
|
|
@@ -55,94 +84,61 @@ Options:
|
|
|
55
84
|
--variant choose a block variant as defined by the template
|
|
56
85
|
```
|
|
57
86
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
1. Interactive mode - without giving a project name, the script will run in interactive mode giving a chance to customize the important options before generating the files.
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
$ npx @wordpress/create-block
|
|
64
|
-
```
|
|
87
|
+
#### `--template`
|
|
65
88
|
|
|
66
|
-
|
|
89
|
+
This argument specifies an _external npm package_ as a template.
|
|
67
90
|
|
|
68
91
|
```bash
|
|
69
92
|
$ npx @wordpress/create-block --template my-template-package
|
|
70
93
|
```
|
|
71
94
|
|
|
72
|
-
|
|
95
|
+
This argument also allows to pick a _local directory_ as a template.
|
|
73
96
|
|
|
74
97
|
```bash
|
|
75
98
|
$ npx @wordpress/create-block --template ./path/to/template-directory
|
|
76
99
|
```
|
|
77
100
|
|
|
78
|
-
|
|
101
|
+
#### `--variant`
|
|
79
102
|
|
|
80
|
-
|
|
81
|
-
$ npx @wordpress/create-block --variant dynamic
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
5. Help – you need to use `npx` to output usage information.
|
|
103
|
+
With this argument, `create-block` will generate a [dynamic block](https://developer.wordpress.org/block-editor/explanations/glossary/#dynamic-block) based on the built-in template.
|
|
85
104
|
|
|
86
105
|
```bash
|
|
87
|
-
$ npx @wordpress/create-block --
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
5. No plugin mode – it is also possible to scaffold only block files into the current directory.
|
|
91
|
-
|
|
92
|
-
```bash
|
|
93
|
-
$ npx @wordpress/create-block --no-plugin
|
|
106
|
+
$ npx @wordpress/create-block --variant dynamic
|
|
94
107
|
```
|
|
95
108
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
## Available Commands
|
|
109
|
+
#### `--help`
|
|
99
110
|
|
|
100
|
-
|
|
111
|
+
With this argument, the `create-block` package outputs usage information.
|
|
101
112
|
|
|
102
113
|
```bash
|
|
103
|
-
$
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
Starts the build for development. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#start).
|
|
107
|
-
|
|
108
|
-
```bash
|
|
109
|
-
$ npm run build
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
Builds the code for production. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#build).
|
|
113
|
-
|
|
114
|
-
```bash
|
|
115
|
-
$ npm run format
|
|
114
|
+
$ npx @wordpress/create-block --help
|
|
116
115
|
```
|
|
117
116
|
|
|
118
|
-
|
|
117
|
+
#### `--no-plugin`
|
|
119
118
|
|
|
120
|
-
|
|
121
|
-
$ npm run lint:css
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
Lints CSS files. [Learn more](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#lint-style).
|
|
119
|
+
With this argument, the `create-block` package runs in _No plugin mode_ which only scaffolds block files into the current directory.
|
|
125
120
|
|
|
126
121
|
```bash
|
|
127
|
-
$
|
|
122
|
+
$ npx @wordpress/create-block --no-plugin
|
|
128
123
|
```
|
|
124
|
+
#### `--wp-env`
|
|
129
125
|
|
|
130
|
-
|
|
126
|
+
With this argument, the `create-block` package will add to the generated plugin the configuration and the script to run [`wp-env` package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) within the plugin. This will allow you to easily set up a local WordPress environment (via Docker) for building and testing the generated plugin.
|
|
131
127
|
|
|
132
128
|
```bash
|
|
133
|
-
$
|
|
129
|
+
$ npx @wordpress/create-block --wp-env
|
|
134
130
|
```
|
|
135
131
|
|
|
136
|
-
|
|
132
|
+
## Available commands in the scaffolded project
|
|
137
133
|
|
|
138
|
-
|
|
139
|
-
$ npm run packages-update
|
|
140
|
-
```
|
|
134
|
+
The plugin folder created when executing this command, is a node package with a modern build setup that requires no configuration.
|
|
141
135
|
|
|
142
|
-
|
|
136
|
+
A set of scripts is available from inside that folder (provided by the `scripts` package) to make your work easier. [Click here](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#available-scripts) for a full description of these commands.
|
|
143
137
|
|
|
144
138
|
_Note: You don’t need to install or configure tools like [webpack](https://webpack.js.org), [Babel](https://babeljs.io) or [ESLint](https://eslint.org) yourself. They are preconfigured and hidden so that you can focus on coding._
|
|
145
139
|
|
|
140
|
+
For example, running the `start` script from inside the generated folder (`npm start`) would automatically start the build for development.
|
|
141
|
+
|
|
146
142
|
## External Project Templates
|
|
147
143
|
|
|
148
144
|
[Click here](https://github.com/WordPress/gutenberg/tree/HEAD/packages/create-block/docs/external-template.md) for information on External Project Templates
|
package/lib/init-block.js
CHANGED
|
@@ -29,6 +29,7 @@ async function initBlockJSON( {
|
|
|
29
29
|
editorScript,
|
|
30
30
|
editorStyle,
|
|
31
31
|
style,
|
|
32
|
+
render,
|
|
32
33
|
customBlockJSON,
|
|
33
34
|
} ) {
|
|
34
35
|
info( '' );
|
|
@@ -57,6 +58,7 @@ async function initBlockJSON( {
|
|
|
57
58
|
editorScript,
|
|
58
59
|
editorStyle,
|
|
59
60
|
style,
|
|
61
|
+
render,
|
|
60
62
|
...customBlockJSON,
|
|
61
63
|
} ).filter( ( [ , value ] ) => !! value )
|
|
62
64
|
),
|
package/lib/scaffold.js
CHANGED
|
@@ -43,6 +43,7 @@ module.exports = async (
|
|
|
43
43
|
editorScript,
|
|
44
44
|
editorStyle,
|
|
45
45
|
style,
|
|
46
|
+
render,
|
|
46
47
|
variantVars,
|
|
47
48
|
customPackageJSON,
|
|
48
49
|
customBlockJSON,
|
|
@@ -101,6 +102,7 @@ module.exports = async (
|
|
|
101
102
|
editorScript,
|
|
102
103
|
editorStyle,
|
|
103
104
|
style,
|
|
105
|
+
render,
|
|
104
106
|
customPackageJSON,
|
|
105
107
|
customBlockJSON,
|
|
106
108
|
...variantVars,
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{{#isDynamicVariant}}
|
|
2
2
|
<p <?php echo get_block_wrapper_attributes(); ?>>
|
|
3
|
-
|
|
3
|
+
<?php esc_html_e( '{{title}} – hello from a dynamic block!', '{{textdomain}}' ); ?>
|
|
4
4
|
</p>
|
|
5
5
|
{{/isDynamicVariant}}
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
{{#description}}
|
|
8
8
|
* Description: {{description}}
|
|
9
9
|
{{/description}}
|
|
10
|
-
* Requires at least:
|
|
10
|
+
* Requires at least: 6.1
|
|
11
11
|
* Requires PHP: 7.0
|
|
12
12
|
* Version: {{version}}
|
|
13
13
|
{{#author}}
|
|
@@ -70,32 +70,12 @@ function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
|
|
|
70
70
|
);
|
|
71
71
|
|
|
72
72
|
register_block_type(
|
|
73
|
-
|
|
73
|
+
$dir,
|
|
74
74
|
array(
|
|
75
75
|
'editor_script' => '{{namespace}}-{{slug}}-block-editor',
|
|
76
76
|
'editor_style' => '{{namespace}}-{{slug}}-block-editor',
|
|
77
77
|
'style' => '{{namespace}}-{{slug}}-block',
|
|
78
|
-
{{#isDynamicVariant}}
|
|
79
|
-
'render_callback' => '{{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback',
|
|
80
|
-
{{/isDynamicVariant}}
|
|
81
78
|
)
|
|
82
79
|
);
|
|
83
80
|
}
|
|
84
81
|
add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );
|
|
85
|
-
{{#isDynamicVariant}}
|
|
86
|
-
|
|
87
|
-
/**
|
|
88
|
-
* Render callback function.
|
|
89
|
-
*
|
|
90
|
-
* @param array $attributes The block attributes.
|
|
91
|
-
* @param string $content The block content.
|
|
92
|
-
* @param WP_Block $block Block instance.
|
|
93
|
-
*
|
|
94
|
-
* @return string The rendered output.
|
|
95
|
-
*/
|
|
96
|
-
function {{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback( $attributes, $content, $block ) {
|
|
97
|
-
ob_start();
|
|
98
|
-
require plugin_dir_path( __FILE__ ) . '/template.php';
|
|
99
|
-
return ob_get_clean();
|
|
100
|
-
}
|
|
101
|
-
{{/isDynamicVariant}}
|
|
@@ -33,53 +33,6 @@
|
|
|
33
33
|
* @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
|
|
34
34
|
*/
|
|
35
35
|
registerBlockType( '{{namespace}}/{{slug}}', {
|
|
36
|
-
/**
|
|
37
|
-
* @see https://make.wordpress.org/core/2020/11/18/block-api-version-2/
|
|
38
|
-
*/
|
|
39
|
-
apiVersion: {{apiVersion}},
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* This is the display title for your block, which can be translated with `i18n` functions.
|
|
43
|
-
* The block inserter will show this name.
|
|
44
|
-
*/
|
|
45
|
-
title: __(
|
|
46
|
-
'{{title}}',
|
|
47
|
-
'{{textdomain}}'
|
|
48
|
-
),
|
|
49
|
-
|
|
50
|
-
{{#description}}
|
|
51
|
-
/**
|
|
52
|
-
* This is a short description for your block, can be translated with `i18n` functions.
|
|
53
|
-
* It will be shown in the Block Tab in the Settings Sidebar.
|
|
54
|
-
*/
|
|
55
|
-
description: __(
|
|
56
|
-
'{{description}}',
|
|
57
|
-
'{{textdomain}}'
|
|
58
|
-
),
|
|
59
|
-
|
|
60
|
-
{{/description}}
|
|
61
|
-
/**
|
|
62
|
-
* Blocks are grouped into categories to help users browse and discover them.
|
|
63
|
-
* The categories provided by core are `text`, `media`, `design`, `widgets`, and `embed`.
|
|
64
|
-
*/
|
|
65
|
-
category: '{{category}}',
|
|
66
|
-
|
|
67
|
-
{{#dashicon}}
|
|
68
|
-
/**
|
|
69
|
-
* An icon property should be specified to make it easier to identify a block.
|
|
70
|
-
* These can be any of WordPress’ Dashicons, or a custom svg element.
|
|
71
|
-
*/
|
|
72
|
-
icon: '{{dashicon}}',
|
|
73
|
-
|
|
74
|
-
{{/dashicon}}
|
|
75
|
-
/**
|
|
76
|
-
* Optional block extended support features.
|
|
77
|
-
*/
|
|
78
|
-
supports: {
|
|
79
|
-
// Removes support for an HTML mode.
|
|
80
|
-
html: false,
|
|
81
|
-
},
|
|
82
|
-
|
|
83
36
|
/**
|
|
84
37
|
* The edit function describes the structure of your block in the context of the editor.
|
|
85
38
|
* This represents what the editor will render when the block is used.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{{#isDynamicVariant}}
|
|
2
2
|
<p <?php echo get_block_wrapper_attributes(); ?>>
|
|
3
|
-
|
|
3
|
+
<?php esc_html_e( '{{title}} – hello from a dynamic block!', '{{textdomain}}' ); ?>
|
|
4
4
|
</p>
|
|
5
5
|
{{/isDynamicVariant}}
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
{{#description}}
|
|
8
8
|
* Description: {{description}}
|
|
9
9
|
{{/description}}
|
|
10
|
-
* Requires at least:
|
|
10
|
+
* Requires at least: 6.1
|
|
11
11
|
* Requires PHP: 7.0
|
|
12
12
|
* Version: {{version}}
|
|
13
13
|
{{#author}}
|
|
@@ -38,33 +38,6 @@
|
|
|
38
38
|
* @see https://developer.wordpress.org/reference/functions/register_block_type/
|
|
39
39
|
*/
|
|
40
40
|
function {{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init() {
|
|
41
|
-
{{#isStaticVariant}}
|
|
42
41
|
register_block_type( __DIR__ . '/build' );
|
|
43
|
-
{{/isStaticVariant}}
|
|
44
|
-
{{#isDynamicVariant}}
|
|
45
|
-
register_block_type(
|
|
46
|
-
__DIR__ . '/build',
|
|
47
|
-
array(
|
|
48
|
-
'render_callback' => '{{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback',
|
|
49
|
-
)
|
|
50
|
-
);
|
|
51
|
-
{{/isDynamicVariant}}
|
|
52
42
|
}
|
|
53
43
|
add_action( 'init', '{{namespaceSnakeCase}}_{{slugSnakeCase}}_block_init' );
|
|
54
|
-
{{#isDynamicVariant}}
|
|
55
|
-
|
|
56
|
-
/**
|
|
57
|
-
* Render callback function.
|
|
58
|
-
*
|
|
59
|
-
* @param array $attributes The block attributes.
|
|
60
|
-
* @param string $content The block content.
|
|
61
|
-
* @param WP_Block $block Block instance.
|
|
62
|
-
*
|
|
63
|
-
* @return string The rendered output.
|
|
64
|
-
*/
|
|
65
|
-
function {{namespaceSnakeCase}}_{{slugSnakeCase}}_render_callback( $attributes, $content, $block ) {
|
|
66
|
-
ob_start();
|
|
67
|
-
require plugin_dir_path( __FILE__ ) . 'build/template.php';
|
|
68
|
-
return ob_get_clean();
|
|
69
|
-
}
|
|
70
|
-
{{/isDynamicVariant}}
|
package/lib/templates.js
CHANGED
|
@@ -26,10 +26,13 @@ const predefinedPluginTemplates = {
|
|
|
26
26
|
description:
|
|
27
27
|
'Example block scaffolded with Create Block tool – no build step required.',
|
|
28
28
|
dashicon: 'smiley',
|
|
29
|
+
supports: {
|
|
30
|
+
html: false,
|
|
31
|
+
},
|
|
29
32
|
wpScripts: false,
|
|
30
|
-
editorScript:
|
|
31
|
-
editorStyle:
|
|
32
|
-
style:
|
|
33
|
+
editorScript: null,
|
|
34
|
+
editorStyle: null,
|
|
35
|
+
style: null,
|
|
33
36
|
},
|
|
34
37
|
templatesPath: join( __dirname, 'templates', 'es5' ),
|
|
35
38
|
variants: {
|
|
@@ -37,6 +40,7 @@ const predefinedPluginTemplates = {
|
|
|
37
40
|
dynamic: {
|
|
38
41
|
slug: 'example-dynamic-es5',
|
|
39
42
|
title: 'Example Dynamic (ES5)',
|
|
43
|
+
render: 'file:./render.php',
|
|
40
44
|
},
|
|
41
45
|
},
|
|
42
46
|
},
|
|
@@ -55,6 +59,7 @@ const predefinedPluginTemplates = {
|
|
|
55
59
|
dynamic: {
|
|
56
60
|
slug: 'example-dynamic',
|
|
57
61
|
title: 'Example Dynamic',
|
|
62
|
+
render: 'file:./render.php',
|
|
58
63
|
},
|
|
59
64
|
},
|
|
60
65
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wordpress/create-block",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.6.0",
|
|
4
4
|
"description": "Generates PHP, JS and CSS code for registering a block for a WordPress plugin.",
|
|
5
5
|
"author": "The WordPress Contributors",
|
|
6
6
|
"license": "GPL-2.0-or-later",
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
"wp-create-block": "./index.js"
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
|
-
"@wordpress/lazy-import": "^1.
|
|
34
|
+
"@wordpress/lazy-import": "^1.9.0",
|
|
35
35
|
"chalk": "^4.0.0",
|
|
36
36
|
"change-case": "^4.1.2",
|
|
37
37
|
"check-node-version": "^4.1.0",
|
|
@@ -48,5 +48,5 @@
|
|
|
48
48
|
"publishConfig": {
|
|
49
49
|
"access": "public"
|
|
50
50
|
},
|
|
51
|
-
"gitHead": "
|
|
51
|
+
"gitHead": "7ac04f446242452d3cb24372f9ca58f0cae97715"
|
|
52
52
|
}
|