Two years ago I wrote a post about creating a Bard addon for adding some custom markup to content – and this was great for Statamic 3. Statamic 4, however, has upgraded under the hood to now use Tiptap 2 – so a few changes are needed.
Read the Statamic docs
Always a good place to start – read the Statamic docs on the matter. They’ve put together a guide covering the key Statamic-specific updates that are needed.
The majority of the changes are pretty straight forward – some namespace changes, and some function changes. There are a few syntax changes, but the docs make it simple to migrate. Take some time to compare the v1 and v2 examples in the docs – these are really useful to see the changes between versions, and shouldn’t create any major issues.
Defining the extension and buttons
Take a look at resources/js/bard.js to see the revisions to the definition of the extension (what Tiptap does with content in the editor) and toolbar button (which uses the menu component).
This is mostly self-explanatory based on the Statamic docs, however the icon definition has changed from a class-based approach to HTML-based, where I’ve just included the raw SVG of the icon. Don’t forget to include your fill="currentColor" too to ensure colours are correctly applied to your icon on light and dark backgrounds.
The syntax is a little different to v1, however this should be pretty straight forward.
When you’re defining your buttons, you’ll notice you have access two variables: buttons and button.
1Statamic.$bard.buttons((buttons, button) => {2 // 3});buttons is an array of all of the buttons, and you can splice your button to be injected where you need it to be.
button is a callback that is required to actually define a button, and accepts an object of button properties like name, text, arguments, and so on.
If you don’t care where your button appears, simply return a button call, like I’ve done (based on the Statamic upgrade docs). But if you want to place your button in a specific location, splice the buttons instead.
Commands
The extension, resources/js/LesMillsClassTypes.js, tells Tiptap what to do with the content nodes and defines the command to run when a class type is set.
Commands are now defined with the addCommands() method, meaning your extension could have multiple commands if needed, and all have a distinct name.
The parseHTML and renderHTML methods are new, and dictate what to do when parsing and rendering. These are basically re-writes of the previous parseDOM and toDOM methods that were in the schema.
Don’t forget the addAttributes method too – this is where allowed attributes for the node must be defined. For this addon, it’s simply the key attribute. But make sure your extension has all of its allowed attributes defined.
1addAttributes() {2 return {3 key: {4 default: '',5 },6 };7},editor.getMarkAttrs
The editor.getMarkAttrs utility has been removed with Tiptap 2. This was used in the 1.0 addon to get the selected mark’s attributes to determine if we need to make the button in the Bard toolbar appear “active” (so it can behave as a toggle), and also to highlight the right class type in the drop down.
We still need this functionality – but it is now available with the getAttributes helper.
1currentKey() {2 // get the lesMillsClassType attribute3 return this.editor.getAttributes('lesMillsClassType').key;4}See this in action in resources/js/LesMillsClassTypes.js.
Other changes
For simplicity, the fonts for icons have been dropped in 2.0.0, and replaced with an inline SVG.
Styles have also been re-written from @apply in the menu component to inline in the actual Vue <template> - helped by Statamic 4’s under-the-hood Tailwind CSS 3 too.
These aren’t about Tiptap 1 to 2 – but more just streamlining and refreshing. Personal preference.
When in doubt…
Read more documentation. And Google. The Tiptap docs are a great place to find out how the new version works, and you may need some trial and error too.
There was trial and error getting this up and running – but that helps with understanding, right? Don’t be afraid to read, experiment and try different things.
Check out v2 of the addon
This addon was created for my use – but is fully functional and installable with composer if you wanted to give it a whirl.
You can check out the latest code at martyf/les-mills-class-types.
The new 2.0.0 version runs only on Statamic 4.
The releases also still have the older 1.2 version which runs with Statamic 3.
