From 4701a23e2e796f49e8877b6e3e86b32736fa9689 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Tue, 14 Jul 2020 16:27:38 -0700 Subject: [PATCH 1/2] Add links for Create a Block Tutorial --- README.md | 9 +- .../designers-developers/developers/README.md | 2 +- .../generate-blocks-with-wp-cli.md | 234 +----------------- .../tutorials/create-block/readme.md | 13 +- .../developers/tutorials/readme.md | 4 +- docs/manifest.json | 42 ++++ docs/readme.md | 9 + docs/toc.json | 8 + 8 files changed, 77 insertions(+), 244 deletions(-) diff --git a/README.md b/README.md index 78567bb190d04..7053ed47127c6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Gutenberg + [![Build Status](https://img.shields.io/travis/com/WordPress/gutenberg/master.svg)](https://travis-ci.com/WordPress/gutenberg) [![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org) @@ -18,17 +19,17 @@ Get hands on: check out the [block editor live demo](https://wordpress.org/guten ### Using Gutenberg -- **Download:** To use the latest release of the Gutenberg plugin on your WordPress site: install from the plugins page in wp-admin, or [download from the WordPress.org plugins repository](https://wordpress.org/plugins/gutenberg/). +- **Download:** To use the latest release of the Gutenberg plugin on your WordPress site: install from the plugins page in wp-admin, or [download from the WordPress.org plugins repository](https://wordpress.org/plugins/gutenberg/). -- **User Documentation:** See the [WordPress Editor documentation](https://wordpress.org/support/article/wordpress-editor/) for detailed docs on using the editor as an author creating posts and pages. +- **User Documentation:** See the [WordPress Editor documentation](https://wordpress.org/support/article/wordpress-editor/) for detailed docs on using the editor as an author creating posts and pages. -- **User Support:** If you have run into an issue, you should check the [Support Forums first](https://wordpress.org/support/forums/). The forums are a great place to get help. If you have a bug to report, please [submit it to the Gutenberg repository](https://github.com/wordpress/gutenberg/issues). Please search prior to creating a new bug to confirm its not a duplicate. +- **User Support:** If you have run into an issue, you should check the [Support Forums first](https://wordpress.org/support/forums/). The forums are a great place to get help. If you have a bug to report, please [submit it to the Gutenberg repository](https://github.com/wordpress/gutenberg/issues). Please search prior to creating a new bug to confirm its not a duplicate. ### Developing for Gutenberg Extending and customizing is at the heart of the WordPress platform, this is no different for the Gutenberg project. The editor and future products can be extended by third-party developers using plugins. -The Getting Started guide will help you run Gutenberg locally to tinker with. See the [Developer Documentation](https://developer.wordpress.org/block-editor/developers/) for extensive tutorials, documentation, and API references on how to extend the editor. +Jump to the [Create a Block tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) for the fastest way to get started extending the block editor. See the [Developer Documentation](https://developer.wordpress.org/block-editor/developers/) for extensive tutorials, documentation, and API references. ### Contribute to Gutenberg diff --git a/docs/designers-developers/developers/README.md b/docs/designers-developers/developers/README.md index ec19e12703bac..f79b1564f1787 100644 --- a/docs/designers-developers/developers/README.md +++ b/docs/designers-developers/developers/README.md @@ -6,7 +6,7 @@ The new editor is highly flexible, like most of WordPress. You can build custom The editor is about blocks, and the main extensibility API is the Block API. It allows you to create your own static blocks, [Dynamic Blocks](/docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md) ( rendered on the server ) and also blocks capable of saving data to Post Meta for more structured content. -If you want to learn more about block creation, the [Blocks Tutorial](/docs/designers-developers/developers/tutorials/block-tutorial/readme.md) is the best place to start. +If you want to learn more about block creation, see the [Create a Block tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) for the best place to start. ## Extending Blocks diff --git a/docs/designers-developers/developers/tutorials/block-tutorial/generate-blocks-with-wp-cli.md b/docs/designers-developers/developers/tutorials/block-tutorial/generate-blocks-with-wp-cli.md index 87d0edb4564ea..74a9921a11f5f 100644 --- a/docs/designers-developers/developers/tutorials/block-tutorial/generate-blocks-with-wp-cli.md +++ b/docs/designers-developers/developers/tutorials/block-tutorial/generate-blocks-with-wp-cli.md @@ -1,235 +1,7 @@ # Generate Blocks with WP-CLI -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/create-guten-block](https://github.com/ahmadawais/create-guten-block) - A zero-configuration developer toolkit for building WordPress Gutenberg block plugins +## WARNING -It might be also a good idea to browse the folder with [all core blocks](https://github.com/WordPress/gutenberg/tree/master/packages/block-library/src) to see how they are implemented. +**Deprecated:** It is not no longer recommended to use WP-CLI or create-guten-block to generate block scaffolding. -## WP-CLI - -Another way of making a 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/). - -### Using `wp scaffold block` - -The following command generates PHP, JS and CSS code for registering a block. - -```bash -wp scaffold block [--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://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ - */ -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(), - filemtime( "$dir/$editor_css" ) - ); - - $style_css = 'movie/style.css'; - wp_register_style( - 'movie-block', - plugins_url( $style_css, __FILE__ ), - array(), - 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://developer.wordpress.org/block-editor/developers/block-api/block-registration/ - */ - var registerBlockType = wp.blocks.registerBlockType; - /** - * Returns a new element of given type. Element is an abstraction layer atop React. - * @see https://developer.wordpress.org/block-editor/packages/packages-element/ - */ - var el = wp.element.createElement; - /** - * Retrieves the translation of text. - * @see https://developer.wordpress.org/block-editor/packages/packages-i18n/ - */ - var __ = wp.i18n.__; - - /** - * Every block starts by registering a new block type definition. - * @see https://developer.wordpress.org/block-editor/developers/block-api/block-registration/ - */ - 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://developer.wordpress.org/block-editor/developers/block-api/block-edit-save/ - * - * @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://developer.wordpress.org/block-editor/developers/block-api/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 -``` +The official script to generate a block is the new [@wordpress/create-block](/packages/create-block/README.md) package. This package follows the new block directory guidelines, and creates the proper block, environment, and standards set by the project. See the new [Create a Block tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) for a complete walk-through. diff --git a/docs/designers-developers/developers/tutorials/create-block/readme.md b/docs/designers-developers/developers/tutorials/create-block/readme.md index 2b043658b9514..2b9b98904b791 100644 --- a/docs/designers-developers/developers/tutorials/create-block/readme.md +++ b/docs/designers-developers/developers/tutorials/create-block/readme.md @@ -1,4 +1,4 @@ -# Create Block Tutorial +# Create a Block Tutorial Let's get you started creating your first block for the WordPress Block Editor. We will create a simple block that allows the user to type a message and styles it. @@ -29,9 +29,8 @@ After activated, go to the block editor and use the inserter to search and add y The create a block tutorials breaks down to the following sections. 1. [WordPress Plugin](/docs/designers-developers/developers/tutorials/create-block/wp-plugin.md) -2. [ESNext Syntax](/docs/designers-developers/developers/tutorials/create-block/esnext-js.md) -3. [Anatomy of a Gutenberg Block ](/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md) -4. [Block Attributes](/docs/designers-developers/developers/tutorials/create-block/block-attributes.md) -5. [Code Implementation](/docs/designers-developers/developers/tutorials/create-block/block-code.md) -6. [Authoring Experience](/docs/designers-developers/developers/tutorials/create-block/author-experience.md) -7. [Finishing Touches](/docs/designers-developers/developers/tutorials/create-block/finishing.md) +2. [Anatomy of a Gutenberg Block ](/docs/designers-developers/developers/tutorials/create-block/block-anatomy.md) +3. [Block Attributes](/docs/designers-developers/developers/tutorials/create-block/block-attributes.md) +4. [Code Implementation](/docs/designers-developers/developers/tutorials/create-block/block-code.md) +5. [Authoring Experience](/docs/designers-developers/developers/tutorials/create-block/author-experience.md) +6. [Finishing Touches](/docs/designers-developers/developers/tutorials/create-block/finishing.md) diff --git a/docs/designers-developers/developers/tutorials/readme.md b/docs/designers-developers/developers/tutorials/readme.md index f07672d2aafa4..e489b6c07c793 100644 --- a/docs/designers-developers/developers/tutorials/readme.md +++ b/docs/designers-developers/developers/tutorials/readme.md @@ -4,7 +4,9 @@ - See the [Getting Started with JavaScript Tutorial](/docs/designers-developers/developers/tutorials/javascript/readme.md) to learn about how to use JavaScript within WordPress. -- The [Blocks Tutorial](/docs/designers-developers/developers/tutorials/block-tutorial/readme.md) is the best place to start to learn more about block creation. +- Beginners: The [Create a Block Tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) walks through creating a block plugin using the `@wordpress/create-block` package; a quick and easy way to start creating your own block. + +- Intermediate: The [Block Tutorial](/docs/designers-developers/developers/tutorials/block-tutorial/readme.md) covers different aspects of block developement. The documentation is slightly dated but still valid, if you are new to block development, start with the Create Block Tutorial above. - See the [Meta Boxes Tutorial](/docs/designers-developers/developers/tutorials/metabox/readme.md) for new ways of extending the editor storing and using post meta data. diff --git a/docs/manifest.json b/docs/manifest.json index 4e1ffbac60127..9a72c293058af 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -521,6 +521,48 @@ "markdown_source": "../docs/designers-developers/developers/tutorials/javascript/esnext-js.md", "parent": "javascript" }, + { + "title": "Create a Block Tutorial", + "slug": "create-block", + "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/readme.md", + "parent": "tutorials" + }, + { + "title": "WordPress Plugin", + "slug": "wp-plugin", + "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/wp-plugin.md", + "parent": "create-block" + }, + { + "title": "Anatomy of a Block", + "slug": "block-anatomy", + "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/block-anatomy.md", + "parent": "create-block" + }, + { + "title": "Block Attributes", + "slug": "block-attributes", + "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/block-attributes.md", + "parent": "create-block" + }, + { + "title": "Code Implementation", + "slug": "block-code", + "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/block-code.md", + "parent": "create-block" + }, + { + "title": "Authoring Experience", + "slug": "author-experience", + "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/author-experience.md", + "parent": "create-block" + }, + { + "title": "Finishing Touches", + "slug": "finishing", + "markdown_source": "../docs/designers-developers/developers/tutorials/create-block/finishing.md", + "parent": "create-block" + }, { "title": "Blocks", "slug": "block-tutorial", diff --git a/docs/readme.md b/docs/readme.md index 10eaaf0fb0f77..c285fc21000f9 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -12,3 +12,12 @@ Blocks treat Paragraphs, Headings, Media, and Embeds all as components that, whe The Editor offers rich new value to users with visual, drag-and-drop creation tools and powerful developer enhancements with modern vendor packages, reusable components, rich APIs and hooks to modify and extend the editor through Custom Blocks, Custom Block Styles and Plugins. +## Quick Links + +- Beginners: The [Create a Block Tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) walks through creating a block plugin using the `@wordpress/create-block` package; a quick and easy way to start creating your own block. + +- [Gutenberg Architecture](/docs/architecture/readme.md) covers the conceptual and tool choices going into the Gutenberg project, from repository structure to packages and tools. + +- [Block API Reference](/docs/designers-developers/developers/block-api/README.md) + +- [Contributors Guide](/docs/contributors/readme.md) covers how **you** can help; be it code, design, documentation, language, or triage, we need you to help make Gutenberg. diff --git a/docs/toc.json b/docs/toc.json index 3ca34fd161f8a..fe18b78aa55b6 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -103,6 +103,14 @@ { "docs/designers-developers/developers/tutorials/javascript/js-build-setup.md": [] }, { "docs/designers-developers/developers/tutorials/javascript/esnext-js.md": [] } ] }, + { "docs/designers-developers/developers/tutorials/create-block/readme.md": [ + { "docs/designers-developers/developers/tutorials/create-block/wp-plugin.md": [] }, + { "docs/designers-developers/developers/tutorials/create-block/block-anatomy.md": [] }, + { "docs/designers-developers/developers/tutorials/create-block/block-attributes.md": [] }, + { "docs/designers-developers/developers/tutorials/create-block/block-code.md": [] }, + { "docs/designers-developers/developers/tutorials/create-block/author-experience.md": [] }, + { "docs/designers-developers/developers/tutorials/create-block/finishing.md": [] } + ] }, { "docs/designers-developers/developers/tutorials/block-tutorial/readme.md": [ { "docs/designers-developers/developers/tutorials/block-tutorial/writing-your-first-block-type.md": [] }, { "docs/designers-developers/developers/tutorials/block-tutorial/applying-styles-with-stylesheets.md": [] }, From a86562864f154399e6ce6bcdc48bf3cc223a44c5 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak <marcus@mkaz.com> Date: Wed, 15 Jul 2020 13:51:57 -0700 Subject: [PATCH 2/2] Change phrasing per review --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7053ed47127c6..037168329a5c2 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ Get hands on: check out the [block editor live demo](https://wordpress.org/guten Extending and customizing is at the heart of the WordPress platform, this is no different for the Gutenberg project. The editor and future products can be extended by third-party developers using plugins. -Jump to the [Create a Block tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) for the fastest way to get started extending the block editor. See the [Developer Documentation](https://developer.wordpress.org/block-editor/developers/) for extensive tutorials, documentation, and API references. +Review the [Create a Block tutorial](/docs/designers-developers/developers/tutorials/create-block/readme.md) for the fastest way to get started extending the block editor. See the [Developer Documentation](https://developer.wordpress.org/block-editor/developers/) for extensive tutorials, documentation, and API references. ### Contribute to Gutenberg