Gutenberg Documentation
While Gutenberg is becoming more stable with each release, documentation is only growing slowly. Many parts are outdated, superficial or completely undocumented.
For more complex or individual requirements you have to dive deep. Gladly the browser console allows you to easily checkout what is driving the editor.
Open your browser developer console and start exploring wp. / wp.data. / wp.api. .
What each function does, can be read in the Block Editor Handbook.
This is all nice, but how do I actually use these?
At this stage of the development, many things are still changing. So using the API direcly is mostly a matter of reading the documentation, checking the implementation within the core codebase and using trial & error.
Some mysteries have already been solved by others or they provide the right lead. Check Stack Overflow and especially the WordPress Development area for solutions.
Its still like a treasure hunt most of the time LOL Perfect for those that love to solve puzzles :)
Just my cup of tea or better coffee!
Do I need to learn React?
It surely is a benefit, as the whole Gutenberg Editor is build upon React. But for simple tweaks its not a must. But once you start going deeper, you will see the benefit and will learn to love React yourself.
What about ES6, ESNext vs ES5?
ECMAScript 6 is also known as ES6 and ECMAScript 2015.
ES5 is on its way out and ES6 is supported on all modern browsers since end of 2016.
Older browsers can be supported using a polyfill, that augments those browsers and allows them to use the new ES6 features.
React and also Gutenberg builds on the new Javascript functionality, but ES5 examples can also be found.
You can also easily compile ES6 to ES5 using Babel in your development environment or online.
Solving Mysteries!
I will be using the following sections to highlight some things that puzzled me and might help others to get a grip on things. I will be extending this, as I discover or solve more Gutenberg mysteries :)
I will keep the example code in ES5 for now, as that is the easiest way to start tinkering. I will also focus on things that can be used from external code. Most of the small code snippets are connected to each other.
Mystery 1: Text Selection & Formats
These little code snippets are all connected and showcase how to retrieve a selection from a block and change or remove a text format.
Wait for domReady
Make sure the editor has loaded and the DOM can be accessed.
|
1 2 3 4 5 |
wp.domReady(function() { // Your code here }); |
Access the active block
|
1 2 3 4 5 6 |
wp.data.select('core/block-editor').getSelectedBlock(); // Block ID - reference var blockUID = wp.data.select('core/block-editor').getSelectedBlock().clientId; |
Access active block selection
|
1 2 3 4 5 6 7 |
// Start of selection var selectionStart = wp.data.select('core/block-editor').getSelectionStart(); // End of selection var selectionEnd = wp.data.select('core/block-editor').getSelectionEnd(); |
The actual offset can be found within the OBJECT.
|
1 2 3 |
wp.data.select('core/block-editor').getSelectionEnd().offset; |
Get block HTML content
|
1 2 3 4 5 6 7 8 9 10 |
// Get block var block = wp.data.select('core/block-editor').getSelectedBlock(); // Attributes var blockAttributes = block.attributes; // Content var blockContent = block.attributes.content; |
Create Richtext object
|
1 2 3 4 5 6 |
var richTextContent = wp.richText.create( { blockContent }); |
Get active text formats
|
1 2 3 |
var activeTextFormats = blockContent.formats; |
Check if format is active for selected text
This function is documented, but wont work from the outside that easily. This normally checks the isActive state of the component. Here a small workaround using Lodash.
|
1 2 3 4 5 6 7 8 9 |
var formatToCheck = "core/text-color"; var formatToCheckisActive = true; if(_.find(value.formats[selectionStart], { type: formatToCheck })) { formatToCheckisActive = false; } |
Formats are saved within the Richtext object under formats and the text formats are stored within arrays that correspond to the actual index + range of the selection. So if a text-color has been applied from index 4 to 8, you will find the corresponding array for that.
Works well and does the trick for now. Here the output from the developer console, showing the arrays for an 18 character long paragraph:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
formats: Array(18) 0: Array(1) 0: {type: "core/bold"} length: 1 __proto__: Array(0) 1: Array(1) 0: {type: "core/bold"} length: 1 __proto__: Array(0) 2: [{…}] 3: [{…}] 4: [{…}] 14: [{…}] 15: [{…}] 16: [{…}] 17: [{…}] length: 18 __proto__: Array(0) |
Apply a new text format to selection
I am using the core/text-color format with applyFormat as an example, can be anything.
|
1 2 3 4 5 6 7 8 9 10 |
richTextContent = wp.richText.applyFormat( richTextContent, { type: 'core/text-color', attributes:{class: "some-color-class"} }, selectionStart, selectionEnd ); |
Insert text at start of selection
insertObject can insert content at the start of the selection, with the rest between selectionStart and selectionEnd getting removed. There is also insert, which allows you to simply add a HTML string into the Richtext value.
|
1 2 3 4 5 6 7 8 |
richTextContent = wp.richText.insertObject( richTextContent, 'core/text-color', selectionStart, selectionEnd ); |
Remove text format from selection
removeFormat allows you to remove a text format from the current selection.
|
1 2 3 4 5 6 7 8 |
richTextContent = wp.richText.removeFormat( richTextContent, 'core/text-color', selectionStart, selectionEnd ); |
Would be nice to use toggleFormat here, but that works within native components and not by selection index as the two calls above.
Convert Richtext value to HTML
|
1 2 3 4 5 |
var prepNewHTML = wp.richText.toHTMLString( {richTextContent } ); |
Replace current block content
|
1 2 3 4 5 6 7 |
wp.data.dispatch( 'core/block-editor' ).updateBlock( blockUID, { attributes: { content: prepNewHTML } } ); |
Whats Next?
I will add some more Gutenberg examples in the future.
