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

Documentation: Add a first block type page to the platform docs #56109

Merged
merged 3 commits into from
Nov 15, 2023
Merged
Changes from 2 commits
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
53 changes: 52 additions & 1 deletion platform-docs/docs/create-block/first-block-type.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,55 @@
sidebar_position: 1
---

# Your first block type
# Your first block type

In addition to the built-in block types, Gutenberg offers a flexible API to build any kind of block type you can imagine.

The `registerBlockType` function registers the block we are going to create and specifies the block type settings.

```js
import { createElement } from "react";
youknowriad marked this conversation as resolved.
Show resolved Hide resolved
import { registerBlockType } from '@wordpress/blocks';

registerBlockType( 'create-block/gutenpride', {
// This is just a flag that tells the block editor that this block
// is using the API version 3 (the latest block type API).
Copy link
Contributor

Choose a reason for hiding this comment

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

Nit: How will the "latest block type API" comment age in these docs?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'm assuming that we will always encourage folks to use the latest apiVersion, so I expect a lookup for apiVersion within our markdown files every time we add a new version.

apiVersion: 3,

// This is the display title for your block type.
title: 'Gutenpride',

// This is the category this block type will be listed in.
// Default categories include: text, media, design, widgets, theme and embed.
category: 'widgets',

// This is a short description for your block type.
// It will be shown in various places in the Gutenberg user interface.
description: 'Example static block scaffolded with Create Block tool.',

// This is an icon for your block type.
icon: (
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M16.7 7.1l-6.3 8.5-3.3-2.5-.9 1.2 4.5 3.4L17.9 8z" />
</svg>
),

edit() {
return <p>Hello from the editor!</p>;
},

save() {
return <p>Hello from the saved content!</p>;
},
t-hamano marked this conversation as resolved.
Show resolved Hide resolved
} );
```

The first parameter in the **registerBlockType** function is the block name. It's composed of two segments a namespace and a specific name. The namespace is used to avoid collisions with other block types from different sources The specific name is the name of the block type. The namespace and the specific name are separated by a slash.
youknowriad marked this conversation as resolved.
Show resolved Hide resolved

The second parameter to the function is the block type object. Two common object properties are **edit** and **save**, these are the key parts of a block.
youknowriad marked this conversation as resolved.
Show resolved Hide resolved

The results of the edit function is what the editor will render to the editor page when the block is inserted.
youknowriad marked this conversation as resolved.
Show resolved Hide resolved

The results of the save function is what the editor will produce as HTML when calling the `serialize` function.
youknowriad marked this conversation as resolved.
Show resolved Hide resolved

At the moment, the `create-block/gutenpride` block type produces a static block at the moment, in the next sections of the tutorial, we will see how to make it editable.
youknowriad marked this conversation as resolved.
Show resolved Hide resolved