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.

Sign up for GitHub

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

Handbook: Updated documentation to reflect the output created currently by npx @wordpress/create-block gutenpride #30353

Merged
merged 1 commit into from
Mar 30, 2021
Merged

Handbook: Updated documentation to reflect the output created currently by npx @wordpress/create-block gutenpride #30353

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
50 changes: 30 additions & 20 deletions docs/getting-started/tutorials/create-block/attributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,29 @@ Attributes are the way a block stores data, they define how a block is parsed to
For this block tutorial, we want to allow the user to type in a message that we will display stylized in the published post. So, we need to add a **message** attribute that will hold the user message. The following code defines a **message** attribute; the attribute type is a string; the source is the text from the selector which is a `div` tag.

```js
attributes: {
message: {
type: 'string',
source: 'text',
selector: 'div',
},
},
registerBlockType( 'create-block/gutenpride', {
apiVersion: 2,
attributes: {
message: {
type: 'string',
source: 'text',
selector: 'div',
default: '', // empty default
},
},
// other settings, like the save and edit functions.
} );
```

Add this to the `index.js` file within the `registerBlockType` function. The `attributes` are at the same level as the title and description fields.
Add this to the `index.js` file within the `registerBlockType` function. The `attributes` are at the same level as the _edit_ and _save_ fields.

When the block loads it will look at the saved content for the block, look for the div tag, take the text portion, and store the content in an `attributes.message` variable.

Note: The text portion is equivalent to `innerText` attribute of a DOM element. For more details and other examples see the [Block Attributes documentation](/docs/reference-guides/block-api/block-attributes.md).

## Edit and Save

The **attributes** are passed to the `edit` and `save` functions, along with a **setAttributes** function to set the values. Additional parameters are also passed in to this functions, see [the edit/save documentation](/docs/reference-guides/block-api/block-edit-save.md) for more details.
The **attributes** are passed to the `edit` and `save` functions, along with a **setAttributes** function to set the values. Additional parameters are also passed in to these functions, see [the edit/save documentation](/docs/reference-guides/block-api/block-edit-save.md) for more details.

The `attributes` is a JavaScript object containing the values of each attribute, or default values if defined. The `setAttributes` is a function to update an attribute.

Expand All @@ -45,27 +50,32 @@ Update the edit.js and save.js files to the following, replacing the existing fu
**edit.js** file:

```js
import { TextControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import { TextControl } from '@wordpress/components';
import './editor.scss';

export default function Edit( { attributes, className, setAttributes } ) {
export default function Edit( { attributes, setAttributes } ) {
return (
<div className={ className }>
<TextControl
label={ __( 'Message', 'gutenpride' ) }
value={ attributes.message }
onChange={ ( val ) => setAttributes( { message: val } ) }
/>
</div>
<div { ...useBlockProps() }>
<TextControl
label={ __( 'Message', 'gutenpride' ) }
value={ attributes.message }
onChange={ ( val ) => setAttributes( { message: val } ) }
/>
</div>
);
}
```

**save.js** file:

```jsx
export default function Save( { attributes, className } ) {
return <div className={ className }>{ attributes.message }</div>;
import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';

export default function save( { attributes } ) {
return <div { ...useBlockProps.save() }>{ attributes.message }</div>;
}
```

Expand Down
43 changes: 23 additions & 20 deletions docs/getting-started/tutorials/create-block/author-experience.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@ import { __ } from '@wordpress/i18n';

export default function Edit( { attributes, className, setAttributes } ) {
return (
<div className={ className }>
<div { ...useBlockProps() }>
<Placeholder
label="Gutenpride Block"
instructions="Add your message"
label={__( 'Gutenpride Block', 'gutenpride' )}
instructions={__( 'Add your message', 'gutenpride' )}
>
<TextControl
value={ attributes.message }
Expand All @@ -45,7 +45,7 @@ This can be used inside a block to control what shows when a parameter is set or

```jsx
return (
<div>
<div {...useBlockProps()}>
{ attributes.message ?
<div>Message: { attributes.message }</div> :
<div>
Expand Down Expand Up @@ -78,14 +78,9 @@ All so this combined together here's what the edit function looks like this:
import { Placeholder, TextControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

export default function Edit( {
attributes,
className,
isSelected,
setAttributes,
} ) {
export default function Edit( { attributes, isSelected, setAttributes } ) {
return (
<div className={ className }>
<div {...useBlockProps()}>
{ attributes.message && ! isSelected ? (
<div>{ attributes.message }</div>
) : (
Expand All @@ -112,29 +107,37 @@ With that in place, rebuild and reload and when you are not editing the message

The switching between a Placeholder and input control works well with a visual element like an image or video, but for the text example in this block we can do better.

The simpler and better solution is to modify the `editor.css` to include the proper stylized text while typing.
The simpler and better solution is to modify the `src/editor.scss` to include the proper stylized text while typing.

Update `editor.css` to:
Update `src/editor.scss` to:

```css
```scss
.wp-block-create-block-gutenpride input[type='text'] {
font-family: Gilbert;
font-size: 64px;
color: inherit;
background: inherit;
border: 0;
}
```

The edit function can simply be:

```jsx
import { useBlockProps } from '@wordpress/block-editor';
import { TextControl } from '@wordpress/components';

export default function Edit( { attributes, className, setAttributes } ) {
import './editor.scss';

export default function Edit( { attributes, setAttributes } ) {
return (
<TextControl
className={ className }
value={ attributes.message }
onChange={ ( val ) => setAttributes( { message: val } ) }
/>
<TextControl
{ ...useBlockProps() }
value={ attributes.message }
onChange={ ( val ) =>
setAttributes( { message: val } )
}
/>
);
}
```
Expand Down
71 changes: 41 additions & 30 deletions docs/getting-started/tutorials/create-block/block-anatomy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,62 +1,73 @@
# Anatomy of a Block

At its simplest, a block in the WordPress block editor is a JavaScript object with a specific set of properties.
At its simplest, a block in the WordPress block editor is a json object with a specific set of properties.

**Note:** Block development uses ESNext syntax, this refers to the latest JavaScript standard. If this is unfamiliar, review the [ESNext syntax documentation](/docs/how-to-guides/javascript/esnext-js.md) to familiarize yourself with the newer syntax used in modern JavaScript development.

Here is the complete code for registering a block:
The javascript part is done in the `src/index.js` file.

```js
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';

registerBlockType( 'create-block/gutenpride', {
apiVersion: 2,
title: 'Gutenpride',
description: 'Example block.',
category: 'widgets',
icon: 'smiley',
supports: {
// Removes support for an HTML mode.
html: false,
},
import './style.scss';

edit: () => {
const blockProps = useBlockProps();
return <div { ...blockProps }> Hello in Editor. </div>;
},
import Edit from './edit';
import save from './save';

save: () => {
const blockProps = useBlockProps.save();
return <div { ...blockProps }> Hello in Save.</div>;
},
registerBlockType( 'create-block/gutenpride', {
apiVersion: 2,
/**
* @see ./edit.js
*/
edit: Edit,
/**
* @see ./save.js
*/
save,
} );
```

The first parameter in the **registerBlockType** function is the block name, this should match exactly to the name registered in the PHP file.

The second parameter to the function is the block object. See the [block registration documentation](/docs/reference-guides/block-api/block-registration.md) for full details.

The **title** is the title of the block shown in the Inserter.
The last two block object properties are **edit** and **save**, these are the key parts of a block. Both properties are functions that are included via the import above.

The **icon** is the icon shown in the Inserter. The icon property expects any Dashicon name as a string, see [list of available icons](https://developer.wordpress.org/resource/dashicons/). You can also provide an SVG object, but for now it's easiest to just pick a Dashicon name.
The results of the edit function is what the editor will render to the editor page when the block is inserted.

The **category** specified is a string and must be one of: "common, formatting, layout, widgets, or embed". You can create your own custom category name, [see documentation for details](/docs/reference-guides/filters/block-filters.md#managing-block-categories).
The results of the save function is what the editor will insert into the **post_content** field when the post is saved. The post_content field is the field in the WordPress database used to store the content of the post.

The last two block object properties are **edit** and **save**, these are the key parts of a block. Both properties should be defined as functions.
Most of the properties are set in the `block.json` file.
```json
{
"apiVersion": 2,
"name": "create-block/gutenpride",
"title": "Gutenpride",
"category": "widgets",
"icon": "smiley",
"description": "Example block written with ESNext standard and JSX support – build step required.",
"supports": {
"html": false
},
"textdomain": "gutenpride",
"editorScript": "file:./build/index.js",
"editorStyle": "file:./build/index.css",
"style": "file:./build/style-index.css"
}
```

The results of the edit function is what the editor will render to the editor page when the block is inserted.
The **title** is the title of the block shown in the Inserter.

The results of the save function is what the editor will insert into the **post_content** field when the post is saved. The post_content field is the field in the WordPress database used to store the content of the post.
The **icon** is the icon shown in the Inserter. The icon property expects any Dashicon name as a string, see [list of available icons](https://developer.wordpress.org/resource/dashicons/). You can also provide an SVG object, but for now it's easiest to just pick a Dashicon name.

**Note:** The `block.json` file is also generated with your plugin. This file is used for registering with the block directory, as you change the properties you should update in both spots. _Development is on-going to simplify this process so only one location is required._
The **category** specified is a string and must be one of: "common, formatting, layout, widgets, or embed". You can create your own custom category name, [see documentation for details](/docs/reference-guides/filters/block-filters.md#managing-block-categories).

## Internationalization

If you look at the generated `src/index.js` file, the block title and description are wrapped in a function that looks like this:
If you look at the generated `src/save.js` file, the block title and description are wrapped in a function that looks like this:

```js
__( 'Gutenpride', 'gutenpride' );
__( 'Gutenpride – hello from the saved content!', 'gutenpride' )
```

This is an internationalization wrapper that allows for the string "Gutenpride" to be translated. The second parameter, "gutenpride" is called the text domain and gives context for where the string is from. The JavaScript internationalization, often abbreviated i18n, matches the core WordPress internationalization process. See the [Internationalization in Plugin Developer Handbook](https://developer.wordpress.org/plugins/internationalization/) for more details.
Expand Down
46 changes: 12 additions & 34 deletions docs/getting-started/tutorials/create-block/block-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,29 @@ Note: The color may not work with all browsers until they support the proper col

## Load Font File

Download and extract the font from the Type with Pride site, and copy it to your plugin directory naming it `gilbert-color.otf`. To load the font file, we need to add CSS using standard WordPress enqueue, [see Including CSS & JavaScript documentation](https://developer.wordpress.org/themes/basics/including-css-javascript/).
Download and extract the font from the Type with Pride site, and copy it in the `src` directory of your plugin naming it `gilbert-color.otf`. To load the font file, we need to add CSS using standard WordPress enqueue, [see Including CSS & JavaScript documentation](https://developer.wordpress.org/themes/basics/including-css-javascript/).

In the `gutenpride.php` file, the enqueue process is already setup from the generated script, so `editor.css` and `style.css` files are loaded using:
In the `gutenpride.php` file, the enqueue process is already setup from the generated script, so `index.css` and `style-index.css` files are loaded using:

```php
register_block_type( 'create-block/gutenpride', array(
'apiVersion' => 2,
'editor_script' => 'create-block-gutenpride-block-editor',
'editor_style' => 'create-block-gutenpride-block-editor',
'style' => 'create-block-gutenpride-block',
) );
function create_block_gutenpride_block_init() {
register_block_type_from_metadata( __DIR__ );
}
add_action( 'init', 'create_block_gutenpride_block_init' );
```

The `editor_style` and `style` parameters refer to the files that match the handles in the `wp_register_style` functions.
This function handles that all style en js files in the `build` folder get handles that are passed on to the `wp_register_style` function.

Note: the `editor_style` loads only within the editor, and after the `style`. The `style` CSS loads in both the editor and front-end — published post view.
The `build/index.css` is compiled from `src/editor.scss` and loads only within the editor, and after the `style-index.css`.
The `build/style-index.css` is compiled from `src/style.scss` and loads in both the editor and front-end — published post view.

## Add CSS Style for Block

We only need to add the style to `style.css` since it will show while editing and viewing the post. Edit the style.css to add the following.
We only need to add the style to `build/style-index.css` since it will show while editing and viewing the post. Edit the `src/style.scss` to add the following.

Note: the block classname is prefixed with `wp-block`. The `create-block/gutenpride` is converted to the classname `.wp-block-create-block-gutenpride`.

```css
```scss
@font-face {
font-family: Gilbert;
src: url( gilbert-color.otf );
Expand All @@ -42,27 +41,6 @@ Note: the block classname is prefixed with `wp-block`. The `create-block/gutenpr
}
```

After updating, reload the post and refresh the browser. If you are using a browser that supports color fonts (Firefox) then you will see it styled.

## Use Sass for Style (optional)

The wp-scripts package provides support for using the Sass/Scss languages, to generate CSS, added in @wordpress/scripts v9.1.0. See the [Sass language site](https://sass-lang.com/) to learn more about Sass.

To use Sass, you need to import a `editor.scss` or `style.scss` in the `index.js` JavaScript file and it will build and output the generated file in the build directory. Note: You need to update the enqueing functions in PHP to load from the correct location.

Add the following imports to **index.js**:

```js
import '../editor.scss';

import Edit from './edit';
import save from './save';
```

Update **gutenpride.php** to enqueue from generated file location:

```php
$editor_css = "build/index.css";
```
After updating, rebuild the block using `npm run build` then reload the post and refresh the browser. If you are using a browser that supports color fonts (Firefox) then you will see it styled.

Next Section: [Authoring Experience](/docs/getting-started/tutorials/create-block/author-experience.md)
11 changes: 10 additions & 1 deletion docs/getting-started/tutorials/create-block/wp-plugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,16 @@ The `register_block_type_from_metadata` function registers the block we are goin
"apiVersion": 2,
"name": "create-block/gutenpride",
"title": "Gutenpride",
"editorScript": "file:./build/index.js"
"category": "widgets",
"icon": "smiley",
"description": "Example block written with ESNext standard and JSX support – build step required.",
"supports": {
"html": false
},
"textdomain": "gutenpride",
"editorScript": "file:./build/index.js",
"editorStyle": "file:./build/index.css",
"style": "file:./build/style-index.css"
}
```

Expand Down