As of the latest WordPress update we all now know about the Gutenberg editor, and whether you love or hate it, it\u2019s here to stay.<\/p>\n
But, as it’s so<\/em> new, it means the APIs are still being worked on – which (naturally) means some things are just not possible or documented yet.<\/p>\n That being said, there are plenty of great resources out there at the moment for creating Gutenberg Blocks. This post assumes you know how to:<\/p>\n What if we want to make a word red, or add a shortcode into our RichText Component with a single click? …and how about from a button on the toolbar?<\/p>\n Sure, we can roll our own and create any kind of editor in our block (we have total flexibility to integrate TinyMCE however we want), but surely there’s a way to do it with the built in RichText component… After all its what the core blocks use, and we like doing things the WP way right?<\/em><\/p>\n This is something that all my googling couldn’t unearth…<\/p>\n After some days digging around and a lot of hacking at code I’ve found there is indeed a way.<\/p>\n Before we get to that, lets get up and running with some familiar Gutenberg Block code.<\/p>\n This post assumes you already know how to create a Gutenberg Block with a View the Code<\/a><\/strong><\/p>\n Nothing out of the ordinary – we’re using If you’re using create-guten-block, then replace Although it’s not documented<\/a> yet we can see Disclaimer: <\/strong>I’m pretty new to React + ES6 and still getting my head around some of their concepts – which is probably why I found this more difficult to understand than some might.<\/em><\/p>\n My first idea was to setup a callback which receives the TinyMCE editor, and then stores a reference to that in the current object:<\/p>\n Fail… What’s wrong with this? …Scope.<\/p>\n One thing I’ve learnt is, the This means that anything we want to use in our Hmm… Where to go from here… where do we store the reference to editor?<\/p>\n If Cue examining the Gutenberg source code (again). Sure enough, there is a Gutenberg component that utilises the Turns out my thinking was a bit limited, what I needed to understand was that So what they’ve done with the List Component is create a React Component<\/a> on Great stuff, this means we can get our button talking to the editor within the same scope.<\/p>\n Lets see what Remember<\/em> What we’ve done here is port everything (our click handlers, return elements) over so that it uses the correct syntax\/structure for a React Component. One thing to note is, if we’re using a React Component it must properly return the Component in the There is one addition though, now that we have This just updates the click callback to interact with And that’s it! Everything should be working together nicely now.<\/strong><\/p>\n From here, the world is your oyster – you have access to the TinyMCE editor which means you can now develop the same functionality into your Gutenberg Blocks as we can with the Classic editor.<\/p>\n NB<\/strong> – you’ll notice in the source a commented \n
\n~ check out create-guten-block<\/a><\/em><\/li>\n
\n~ official docs<\/a> have got you covered<\/em><\/li>\n
\n~ check out the excellent video<\/a> by Zac Gordon<\/em><\/li>\n<\/ol>\nThe Problem<\/h2>\n
The Solution<\/h2>\n
1. Create a Block with RichText and BlockControls (Toolbar) Components<\/h3>\n
RichText<\/code> component. If not, you should familiarise yourself with the resources above. Your code should look something like this:<\/p>\nregisterBlockType<\/code> to setup our block, adding RichText<\/code> and BlockControls<\/code> components to our edit<\/code> function, with a couple of functions handling the changes and setting the content.<\/p>\nsrc\/block\/block.js<\/code> with the above Gist.<\/em><\/p>\n2. Accessing the editor<\/h3>\n
Using `onSetup`<\/h4>\n
onSetup<\/code> is a callback we can utilise<\/a> which will return a copy of the TinyMCE editor (RichText<\/code> components use TinyMCE). However for me at least this was not the tricky part.<\/p>\nfunction onEditorSetup( editor ) {\n this.editor = editor;\n}<\/pre>\nedit<\/code> function is returned for each instance of our block in the post editor view, but the parent object with the edit<\/code> function is invoked only once when setting up the block as a block type (should be pretty obvious really, took me a minute).<\/p>\nedit<\/code> function, must live only inside the edit<\/code> function (pretty much) so that each instance is self contained, and interacts with its own objects…<\/p>\nExtending the `edit` function<\/h4>\n
edit<\/code> is a function, then I could see no reliable way to keep track of each instance of our editor and controls. I did think about wrapping RichText in a React Component so I could keep a reference to the editor, within a certain scope, but then realised that I’d run in to the same problem when trying to get the toolbar button to interact with it. It was a bit beyond me.<\/p>\nonSetup<\/code> callback<\/a> and provides a great example of how to handle this scenario correctly.<\/p>\nedit<\/code> just needs to return a React Component.<\/p>\nedit<\/code>, and return the RichText<\/code> and all the trimmings together within<\/em> the Component, so they can access shared local variables, functions etc.<\/p>\nedit<\/code> might look like, using inspiration from the Gutenberg source (check the inline comments):<\/p>\nedit: class extends Component {\n \n \/\/standard constructor for a component\n constructor() {\n super( ...arguments );\n \n \/\/make sure we bind `this` to the current component within our callbacks\n this.setupEditor = this.setupEditor.bind( this );\n this.onChangeContent = this.onChangeContent.bind( this );\n\n this.state = {\n \/\/we don't need our component to manage a state in this instance\n };\n }\n \n \/\/same as before, except `this` actually references this component\n setupEditor( editor ) {\n this.editor = editor;\n }\n \n \/\/no change here again, except the binding of `this`\n onChangeContent( newContent ) {\n this.props.setAttributes( { content: newContent } );\n }\n \n \/\/slightly different pattern of syntax here, we're returning a function\n onClickShortcodeButton() {\n return () => {\n \n \/\/the content we want to insert\n var myContent = '[myshortcode][\/myshortcode]';\n \n if ( this.editor ) {\n \/\/execCommand is a TinyMCE function\n this.editor.execCommand( 'mceInsertContent', false, myContent );\n }\n };\n }\n \n \/\/all react components require render - this is what will be returned by our component\n render() {\n const {\n attributes,\n setAttributes,\n className,\n } = this.props;\n \n return (\n <Fragment>\n <BlockControls\n controls={ [\n {\n icon: 'edit',\n title: __( 'Insert Shortcode' ),\n onClick: this.onClickShortcodeButton(),\n },\n ] }\n \/>\n <RichText\n \/\/getSettings={ this.getEditorSettings } \/\/a useful callback for adding params to TinyMCE on setup\n onSetup={ this.setupEditor }\n key = { 'editable' }\n tagName = { 'p' }\n className = { className }\n onChange = { this.onChangeContent }\n value = { attributes.content}\n \/>\n <\/Fragment>\n );\n }\n},<\/pre>\nedit<\/code> is now a React + ES6 Component, so the syntax is fairly standard, but not what you might be used to seeing in a Block.<\/em><\/p>\nrender<\/code> method, which looks a lot like the return of our old edit<\/code> function.<\/p>\nthis.editor<\/code> working within the scope of the Component, I’ve added the final functionality allowing the button to interact with it:<\/p>\nonClickShortcodeButton() {\n\treturn () => {\n\t\t\n\t\t\/\/the content we want to insert\n\t\tvar myContent = '[myshortcode][\/myshortcode]';\n\t\t\n\t\tif ( this.editor ) {\n\t\t\t\/\/execCommand is a TinyMCE function\n\t\t\tthis.editor.execCommand( 'mceInsertContent', false, myContent );\n\t\t}\n\t};\n}<\/pre>\nthis.editor<\/code>, and in this case we wanted to insert a shortcode using execCommand<\/code>.<\/p>\ngetSettings<\/code> callback, this allows you to modify the settings object that gets passed into TinyMCE when being initialised – might be useful!<\/em><\/p>\nFiles<\/h4>\n