-
Notifications
You must be signed in to change notification settings - Fork 4.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' into rnmobile/372-add-title-to-gutenberg-mobile
- Loading branch information
Showing
276 changed files
with
2,169 additions
and
467 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| build | ||
| build-module | ||
| node_modules | ||
| packages/tests-e2e/plugins | ||
| packages/e2e-tests/plugins | ||
| vendor | ||
| packages/block-serialization-spec-parser/parser.js |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
48 changes: 48 additions & 0 deletions
48
docs/designers-developers/developers/tutorials/format-api/1-register-format.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # Register a new format | ||
|
|
||
| The first thing you're going to do in this tutorial is to register the new format that the plugin intends to apply. WordPress has the [`registerFormatType`](/packages/rich-text/README.md#registerFormatType) function to do so. | ||
|
|
||
| Let's prepare a minimal plugin to make this work. Create a new folder and a file named `my-custom-format.php` within it containing the necessary PHP code to register and enqueue the JavaScript assets: | ||
|
|
||
| ```php | ||
| <?php | ||
| /** | ||
| * Plugin Name: My custom format | ||
| */ | ||
|
|
||
| function my_custom_format_script_register() { | ||
| wp_register_script( | ||
| 'my-custom-format-js', | ||
| plugins_url( 'my-custom-format.js', __FILE__ ), | ||
| array( 'wp-rich-text' ) | ||
| ); | ||
| } | ||
| add_action( 'init', 'my_custom_format_script_register' ); | ||
|
|
||
| function my_custom_format_enqueue_assets_editor() { | ||
| wp_enqueue_script( 'my-custom-format-js' ); | ||
| } | ||
| add_action( 'enqueue_block_editor_assets', 'my_custom_format_enqueue_assets_editor' ); | ||
| ``` | ||
|
|
||
| Then add a new file named `my-custom-format.js` with the following contents: | ||
|
|
||
| ```js | ||
| ( function( wp ) { | ||
| wp.richText.registerFormatType( | ||
| 'my-custom-format/sample-output', { | ||
| title: 'Sample output', | ||
| tagName: 'samp', | ||
| className: null, | ||
| } | ||
| ); | ||
| } )( window.wp ); | ||
| ``` | ||
|
|
||
| Make that plugin available in your WordPress setup and activate it. Then, load a new page/post. | ||
|
|
||
| The list of available format types is maintained in the `core/rich-text` store. You can query the store to check that your custom format is now avaliable. To do so, run this code in your browser's console: | ||
|
|
||
| wp.data.select( 'core/rich-text' ).getFormatTypes(); | ||
|
|
||
| It'll return an array containing the format types, including your own. |
37 changes: 37 additions & 0 deletions
37
docs/designers-developers/developers/tutorials/format-api/2-toolbar-button.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| # Add a button to the toolbar | ||
|
|
||
| Now that the format is avaible, the next step is to surface it to the UI. You can make use of the [`RichTextToolbarButton`](/packages/editor/src/components/rich-text/README.md#RichTextToolbarButton) component to extend the format toolbar. | ||
|
|
||
| Paste this code in `my-custom-format.js`: | ||
|
|
||
| ```js | ||
| ( function( wp ) { | ||
| var MyCustomButton = function( props ) { | ||
| return wp.element.createElement( | ||
| wp.editor.RichTextToolbarButton, { | ||
| icon: 'editor-code', | ||
| title: 'Sample output', | ||
| onClick: function() { | ||
| console.log( 'toggle format' ); | ||
| }, | ||
| } | ||
| ); | ||
| } | ||
| wp.richText.registerFormatType( | ||
| 'my-custom-format/sample-output', { | ||
| title: 'Sample output', | ||
| tagName: 'samp', | ||
| className: null, | ||
| edit: MyCustomButton, | ||
| } | ||
| ); | ||
| } )( window.wp ); | ||
| ``` | ||
|
|
||
| **Important**: note that this code is using two new utilities (`wp.element.createElement`, and `wp.editor.RichTextToolbarButton`) so don't forget adding the corresponding `wp-element` and `wp-editor` packages to the dependencies array in the PHP file along with the existing `wp-rich-text`. | ||
|
|
||
| Let's check that everything is working as expected. Reload the post/page and select a text block. Make sure that the new button was added to the format toolbar, it uses the [editor-code dashicon](https://developer.wordpress.org/resource/dashicons/#editor-code), and the hover text is what you set in the title: | ||
|
|
||
|  | ||
|
|
||
| You may also want to check that upon clicking the button the `toggle format` message is shown in your browser's console. |
43 changes: 43 additions & 0 deletions
43
docs/designers-developers/developers/tutorials/format-api/3-apply-format.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| # Apply the format when the button is clicked | ||
|
|
||
| So far, your custom button doesn't modify the text selected, it only renders a message in the console. Let's change that. | ||
|
|
||
| The [rich-text package](/packages/rich-text/README.md) offers a few utilities to work with formats: [applyFormat](/packages/rich-text/README.md#applyFormat), [removeFormat](/packages/rich-text/README.md#removeFormat), and [toggleFormat](/packages/rich-text/README.md#toggleFormat). In this particular example, the format you want to apply (the `<samp>` tag) may be considered binary - either a text selection has the tag or not. Taking that into account, the `toggleFormat` primitive seems more convenient. | ||
|
|
||
| Update `my-custom-format.js` with this new code: | ||
|
|
||
| ```js | ||
| ( function( wp ) { | ||
| var MyCustomButton = function( props ) { | ||
| return wp.element.createElement( | ||
| wp.editor.RichTextToolbarButton, { | ||
| icon: 'editor-code', | ||
| title: 'Sample output', | ||
| onClick: function() { | ||
| props.onChange( wp.richText.toggleFormat( | ||
| props.value, | ||
| { type: 'my-custom-format/sample-output' } | ||
| ) ); | ||
| }, | ||
| isActive: props.isActive, | ||
| } | ||
| ); | ||
| } | ||
| wp.richText.registerFormatType( | ||
| 'my-custom-format/sample-output', { | ||
| title: 'Sample output', | ||
| tagName: 'samp', | ||
| className: null, | ||
| edit: MyCustomButton, | ||
| } | ||
| ); | ||
| } )( window.wp ); | ||
| ``` | ||
|
|
||
| Now, let's check that is working as intended: reload the post/page, make a text selection, click the button, and then change to HTML view to confirm that the tag was effectively applied. | ||
|
|
||
| The expected behavior is that the format will be toggled, meaning that the text selected will be wrapped by a `<samp>` tag if it isn't yet, or the tag will be removed if the selection is already wrapped with the tag. Notice that the button renders a different style depending on whether the selection has the tag or not as well - this is controlled by the `isActive` property of the `RichTextToolbarButton` component. | ||
|
|
||
| Your browser may have already displayed the selection differently once the tag was applied, but you may want to use a special style of your own. You can use the `className` option in [`registerFormatType`](/packages/rich-text/README.md#registerFormatType) to target the new element by class name: if `className` is set, it'll be added to the new element. | ||
|
|
||
| That's it. This is all that is necessary to make a custom format available in the new editor. From here, you may want to check out other [tutorials](/docs/designers-developers/developers/tutorials/) or apply your new knowledge to your next plugin! |
13 changes: 13 additions & 0 deletions
13
docs/designers-developers/developers/tutorials/format-api/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| # Introduction to the Format API | ||
|
|
||
| The purpose of this tutorial is to introduce you to the Format API. The Format API makes it possible for developers to add custom buttons to the formatting toolbar and have them apply a _format_ to a text selection. Bold is an example of a standard button in the formatting toolbar. | ||
|
|
||
| In WordPress lingo, a _format_ is a [HTML tag with text-level semantics](https://www.w3.org/TR/html5/textlevel-semantics.html#text-level-semantics-usage-summary) used to give some special meaning to a text selection. For example, in this tutorial, the button to be hooked into the format toolbar will let users wrap a particular text selection with the [`<samp>` HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp). | ||
|
|
||
| If you are unfamiliar with how to work with WordPress plugins and JavaScript, you may want to check the [JavaScript Tutorial](/docs/designers-developers/developers/tutorials/javascript/readme.md) first. | ||
|
|
||
| ## Table of contents | ||
|
|
||
| 1. [Register a new format](/docs/designers-developers/developers/tutorials/format-api/1-register-format.md) | ||
| 2. [Add a button to the toolbar](/docs/designers-developers/developers/tutorials/format-api/2-toolbar-button.md) | ||
| 3. [Apply the format when the button is clicked](/docs/designers-developers/developers/tutorials/format-api/3-apply-format.md) |
17 changes: 17 additions & 0 deletions
17
docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| # Store Post Meta with a Block | ||
|
|
||
| Typically, blocks store their attribute values in the serialised block HTML. However, you can also create a block that saves its attribute values as post meta, which can be accessed programatically anywhere in your template. | ||
|
|
||
| In this short tutorial you will create one of these blocks, which will prompt a user for a single value, and save it as post meta. | ||
|
|
||
| For background around the thinking of blocks as the interface, please see the [Principles section](/docs/contributors/principles.md) of the handbook. | ||
|
|
||
| Before starting this tutorial, you will need a plugin to hold your code. Please take a look at the first two steps of [the JavaScript tutorial](/docs/designers-developers/developers/tutorials/javascript/readme.md) for information setting up a plugin. | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| 1. [Register Meta Field](/docs/designers-developers/developers/tutorials/metabox/meta-block-2-register-meta.md) | ||
| 2. [Add Meta Block](/docs/designers-developers/developers/tutorials/metabox/meta-block-3-add.md) | ||
| 3. [Use Post Meta Data](/docs/designers-developers/developers/tutorials/metabox/meta-block-4-use-data.md) | ||
| 4. [Finishing Touches](/docs/designers-developers/developers/tutorials/metabox/meta-block-5-finishing.md) | ||
|
|
Oops, something went wrong.