Skip to content

Commit

Permalink
Docs: Add page explaining how to scaffold blocks (#4404)
Browse files Browse the repository at this point in the history
  • Loading branch information
gziolo committed Jan 18, 2018
1 parent b866d21 commit e24460c
Show file tree
Hide file tree
Showing 2 changed files with 245 additions and 0 deletions.
239 changes: 239 additions & 0 deletions docs/blocks-scaffolding.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,239 @@
# Speeding up writing blocks

It turns out that writing the simplest possible block which contains only static content might not be the easiest task. It requires to follow closely the steps described in the documentation. It stems from the fact that you need to create at least 2 files and integrate your code with the existing APIs. One way to mitigate this inconvenience is to copy the source code of the existing block from one of the repositories that share working examples:
- [WordPress/gutenberg-examples](https://github.com/WordPress/gutenberg-examples) - the official examples for extending Gutenberg with plugins which create blocks
- [zgordon/gutenberg-course](https://github.com/zgordon/gutenberg-course) - a repository for Zac Gordon's Gutenberg Development Course
- [ahmadawais/Gutenberg-Boilerplate](https://github.com/ahmadawais/Gutenberg-Boilerplate) - an inline documented starter WordPress plugin for the new Gutenberg editor

## WP-CLI

Another way of making developer's life easier is to use [WP-CLI](http://wp-cli.org/), which provides a command-line interface for many actions you might perform on the WordPress instance. One of the commands generates all the code required to register a Gutenberg block for a plugin or theme.

### Installing

Before installing `WP-CLI`, please make sure your environment meets the minimum requirements:

* UNIX-like environment (OS X, Linux, FreeBSD, Cygwin); limited support in Windows environment
* PHP 5.3.29 or later
* WordPress 3.7 or later

Once you’ve verified requirements, you should follow the [installation instructions](http://wp-cli.org/#installing). Downloading the Phar file is the recommended installation method for most users. Should you need, see also the documentation on [alternative installation methods](https://make.wordpress.org/cli/handbook/installing/).

_Important_: To use scaffolding command for blocks you temporary need (until v1.5.0 is released) to run `wp cli update --nightly` to use the latest nightly build of `WP-CLI`. The nightly build is more or less stable enough for you to use in your development environment, and always includes the latest and greatest `WP-CLI` features.

### Using `wp scaffold block`

The following command generates PHP, JS and CSS code for registering a Gutenberg block.

```bash
wp scaffold block <slug> [--title=<title>] [--dashicon=<dashicon>] [--category=<category>] [--theme] [--plugin=<plugin>] [--force]
```

Please refer to the [command documentation](https://github.com/wp-cli/scaffold-command#wp-scaffold-block) to learn more about the available options for the block.

When you scaffold a block you must provide at least a `slug` name and either the `theme` or `plugin` name. In most cases, we recommended pairing blocks with plugins rather than themes, because only using plugin ensures that all blocks will still work when your theme changes.

### Examples

Here are some examples using `wp scaffold block` in action.

#### Create a block inside the plugin

The following command generates a `movie` block with the `My movie block` title for the existing plugin named `movies`:

```bash
$ wp scaffold block movie --title="My movie block" --plugin=movies
Success: Created block 'My movie block'.
```

This will generate 4 files inside the `movies` plugin directory. All files contain inline documentation that will help to apply any further customizations to the block. It's worth mentioning that it is currently possible to scaffold only blocks containing static content and JavaScript code is written using ECMAScript 5 (ES5) standard which works with all modern browsers.

`movies/blocks/movie.php` - you will have to manually include this file in your main plugin file:
```php
<?php
/**
* Functions to register client-side assets (scripts and stylesheets) for the
* Gutenberg block.
*
* @package movies
*/

/**
* Registers all block assets so that they can be enqueued through Gutenberg in
* the corresponding context.
*
* @see https://wordpress.org/gutenberg/handbook/blocks/writing-your-first-block-type/#enqueuing-block-scripts
*/
function movie_block_init() {
$dir = dirname( __FILE__ );

$block_js = 'movie/block.js';
wp_register_script(
'movie-block-editor',
plugins_url( $block_js, __FILE__ ),
array(
'wp-blocks',
'wp-i18n',
'wp-element',
),
filemtime( "$dir/$block_js" )
);

$editor_css = 'movie/editor.css';
wp_register_style(
'movie-block-editor',
plugins_url( $editor_css, __FILE__ ),
array(
'wp-blocks',
),
filemtime( "$dir/$editor_css" )
);

$style_css = 'movie/style.css';
wp_register_style(
'movie-block',
plugins_url( $style_css, __FILE__ ),
array(
'wp-blocks',
),
filemtime( "$dir/$style_css" )
);

register_block_type( 'movies/movie', array(
'editor_script' => 'movie-block-editor',
'editor_style' => 'movie-block-editor',
'style' => 'movie-block',
) );
}
add_action( 'init', 'movie_block_init' );
```

`movies/blocks/movie/block.js`:
```js
( function( wp ) {
/**
* Registers a new block provided a unique name and an object defining its behavior.
* @see https://github.com/WordPress/gutenberg/tree/master/blocks#api
*/
var registerBlockType = wp.blocks.registerBlockType;
/**
* Returns a new element of given type. Element is an abstraction layer atop React.
* @see https://github.com/WordPress/gutenberg/tree/master/element#element
*/
var el = wp.element.createElement;
/**
* Retrieves the translation of text.
* @see https://github.com/WordPress/gutenberg/tree/master/i18n#api
*/
var __ = wp.i18n.__;

/**
* Every block starts by registering a new block type definition.
* @see https://wordpress.org/gutenberg/handbook/block-api/
*/
registerBlockType( 'movies/movie', {
/**
* This is the display title for your block, which can be translated with `i18n` functions.
* The block inserter will show this name.
*/
title: __( 'My movie block' ),

/**
* Blocks are grouped into categories to help users browse and discover them.
* The categories provided by core are `common`, `embed`, `formatting`, `layout` and `widgets`.
*/
category: 'widgets',

/**
* Optional block extended support features.
*/
supports: {
// Removes support for an HTML mode.
html: false,
},

/**
* 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://wordpress.org/gutenberg/handbook/block-edit-save/#edit
*
* @param {Object} [props] Properties passed from the editor.
* @return {Element} Element to render.
*/
edit: function( props ) {
return el(
'p',
{ className: props.className },
__( 'Hello from the editor!' )
);
},

/**
* The save function defines the way in which the different attributes should be combined
* into the final markup, which is then serialized by Gutenberg into `post_content`.
* @see https://wordpress.org/gutenberg/handbook/block-edit-save/#save
*
* @return {Element} Element to render.
*/
save: function() {
return el(
'p',
{},
__( 'Hello from the saved content!' )
);
}
} );
} )(
window.wp
);
```

`movies/blocks/movie/editor.css`:
```css
/**
* The following styles get applied inside the editor only.
*
* Replace them with your own styles or remove the file completely.
*/

.wp-block-movies-movie {
border: 1px dotted #f00;
}
```

`movies/blocks/movie/style.css`:
```css
/**
* The following styles get applied both on the front of your site and in the editor.
*
* Replace them with your own styles or remove the file completely.
*/

.wp-block-movies-movie {
background-color: #000;
color: #fff;
padding: 2px;
}
```

#### Create a block inside the theme

It is also possible to scaffold the same `movie` block and include it into the existing theme, e.g. `simple-life`:

```bash
$ wp scaffold block movie --theme=simple-life
Success: Created block 'Movie block'.
```

#### Create a plugin and add two blocks

If you don't have an existing plugin you can create a new one and add two blocks with `WP-CLI` as follows:

```bash
# Create plugin called books
$ wp scaffold plugin books
# Add a block called book to plugin books
$ wp scaffold block book --title="Book" --plugin=books
# Add a second block to plugin called books.
$ wp scaffold block books --title="Book List" --plugin=books
```
6 changes: 6 additions & 0 deletions docs/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,12 @@
"markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks-dynamic.md",
"parent": "blocks"
},
{
"title": "Speeding up writing blocks",
"slug": "speeding-up-writing-blocks",
"markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/blocks-scaffolding.md",
"parent": "blocks"
},
{
"title": "Reference",
"slug": "reference",
Expand Down

0 comments on commit e24460c

Please sign in to comment.