Skip to content

Commit

Permalink
Merge branch 'trunk' into update/shim-default-block-editor-settings
Browse files Browse the repository at this point in the history
  • Loading branch information
@gziolo
gziolo authored Mar 30, 2021
2 parents 8296b33 + 12c2326 commit a279f7e
Show file tree
Hide file tree
Showing 182 changed files with 29,855 additions and 32,115 deletions.
5 changes: 3 additions & 2 deletions .github/CODEOWNERS
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@
/packages/create-block @gziolo @mkaz
/packages/create-block-tutorial-template @gziolo
/packages/custom-templated-path-webpack-plugin @ntwb @nerrad @ajitbohra
/packages/dependency-extraction-webpack-plugin @gziolo
/packages/docgen @nosolosw
/packages/e2e-test-utils @ntwb @nerrad @ajitbohra
/packages/e2e-tests @ntwb @nerrad @ajitbohra
Expand All @@ -63,9 +64,9 @@
/packages/library-export-default-webpack-plugin @ntwb @nerrad @ajitbohra
/packages/npm-package-json-lint-config @gziolo @ntwb @nerrad @ajitbohra
/packages/postcss-themes @ntwb @nerrad @ajitbohra
/packages/scripts @gziolo @ntwb @nerrad @ajitbohra
/packages/dependency-extraction-webpack-plugin @gziolo
/packages/prettier-config @ntwb @gziolo
/packages/scripts @gziolo @ntwb @nerrad @ajitbohra
/packages/stylelint-config @ntwb

# UI Components
/packages/components @ajitbohra @jaymanpandya @chrisvanpatten
Expand Down
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,4 +23,4 @@
- [ ] I've tested my changes with keyboard and screen readers. <!-- Instructions: https://github.com/WordPress/gutenberg/blob/HEAD/docs/contributors/accessibility-testing.md -->
- [ ] My code has proper inline documentation. <!-- Guidelines: https://developer.wordpress.org/coding-standards/inline-documentation-standards/javascript/ -->
- [ ] I've included developer documentation if appropriate. <!-- Handbook: https://developer.wordpress.org/block-editor/ -->
- [ ] I've updated all React Native files affected by any refactorings/renamings in this PR. <!-- React Native mobile Gutenberg guidelines: https://github.com/WordPress/gutenberg/blob/HEAD/docs/contributors/code/native-mobile.md -->
- [ ] I've updated all React Native files affected by any refactorings/renamings in this PR (please manually search all `*.native.js` files for terms that need renaming or removal). <!-- React Native mobile Gutenberg guidelines: https://github.com/WordPress/gutenberg/blob/HEAD/docs/contributors/code/native-mobile.md -->
12 changes: 6 additions & 6 deletions docs/contributors/code/native-mobile.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@

Intertwined with the web codepaths, the Gutenberg repo also includes the [React Native](https://facebook.github.io/react-native/) based mobile tree.

## Running Gutenberg Mobile on Android and iOS

For instructions on how to run the **Gutenberg Mobile Demo App** on Android or iOS, see [Getting Started for the React Native based Mobile Gutenberg](/docs/contributors/code/getting-started-native-mobile.md)
## Mind the mobile

Also, the mobile client is packaged and released via the [official WordPress apps](https://wordpress.org/mobile/). Even though the build pipeline is slightly different then the mobile demo apps and lives in its own repo for now ([here's the native mobile repo](https://github.com/wordpress-mobile/gutenberg-mobile)), the source code itself is taken directly from this repo and the "web" side codepaths.
Contributors need to ensure that they update any affected native mobile files during code refactorings because we cannot yet rely on automated tooling to do this for us. For example, renaming a function or a prop should also be performed in the native modules too, otherwise, the mobile client will break. We have added some mobile specific CI tests as safeguards in place in PRs, but we're still far from done. Please bear with us and thank you in advance. ❤️🙇‍

## Native mobile specific files

The majority of the code shared with native mobile is in the very same JavaScript module and SASS style files. In the cases where the code paths need to diverge, a `.native.js` or `.native.scss` variant of the file is created. In some cases, platform specific files can be also found for Android (`.android.js`) or iOS (`.ios.js`).

## Mind the mobile
## Running Gutenberg Mobile on Android and iOS

Our tooling isn't as good yet as we'd like to and it's hard to have a good awareness of those native mobile files. That means that contributors need to manually pay attention to update the native mobile files during code refactorings. For example, renaming a function or a prop should also be performed in the native modules too, otherwise, the mobile client will break. We have added some mobile specific CI tests as safeguards in place in PRs, but we're still far from done. Please bear with us and thank you in advance. ❤️🙇‍
For instructions on how to run the **Gutenberg Mobile Demo App** on Android or iOS, see [Getting Started for the React Native based Mobile Gutenberg](/docs/contributors/code/getting-started-native-mobile.md)

Also, the mobile client is packaged and released via the [official WordPress apps](https://wordpress.org/mobile/). Even though the build pipeline is slightly different then the mobile demo apps and lives in its own repo for now ([here's the native mobile repo](https://github.com/wordpress-mobile/gutenberg-mobile)), the source code itself is taken directly from this repo and the "web" side codepaths.

## Native mobile E2E tests in Continuous Integration

Expand Down
50 changes: 30 additions & 20 deletions docs/getting-started/tutorials/create-block/attributes.md
View file
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
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
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
Loading

0 comments on commit a279f7e

Please sign in to comment.