Add Styles to Drupal Media with Config

With Drupal's upgrade to CKEditor 5, users can now add their own attributes or styles to the media toolbar using the new DrupalElementStyle plugin via YAML definitions …without writing a single line of JavaScript!

Let's look at an example where we want to add options for an attribute called data-attribution as ‘in-house', ‘external', and ‘none' in the media toolbar. Create a file in your module's root named mymodule.ckeditor5.yml with the following:

mymodule_mediaAttribution:
 provider: mymodule
 ckeditor5:
 plugins:
 - drupalMedia.DrupalElementStyle
 config:
 drupalElementStyles:
 attribution:
 - name: 'in-house'
 title: 'In house'
 attributeName: 'data-attribution'
 attributeValue: 'in-house'
 modelElements: [ 'drupalMedia' ]
 icon: '<svg>in_house_icon</svg>'
 - name: 'external'
 title: 'External source'
 attributeName: 'data-attribution'
 attributeValue: 'external'
 modelElements: [ 'drupalMedia' ]
 icon: '<svg>external_icon</svg>'
 - name: 'none'
 title: 'Unknown'
 isDefault: true
 modelElements: [ 'drupalMedia' ]
 icon: '<svg>unknown_icon</svg>'
 drupalMedia:
 toolbar:
 - '|'
 - 'drupalElementStyle:attribution:none'
 - 'drupalElementStyle:attribution:in-house'
 - 'drupalElementStyle:attribution:external'
 - '|'
 drupal:
 label: Media attribution
 elements:
 - <drupal-media data-attribution>
 conditions:
 plugins: [media_media]
</drupal-media>

Under the ckeditor.plugins key we specify that this requires the DrupalElementStyle plugin in the drupalMedia package. Next we provide configuration for this plugin, at ckeditor5.config.drupalElementStyles. We choose a unique key to represent this new capability and since it's about source attribution, we go with attribution.

The array of 3 possible choices define 3 unique attribute values, all on a new attribute to be set when using this plugin: data-attribution. See the documentation in the DrupalElementStyleEditing plugin for the expected structure.

The drupal.toolbar configuration is responsible for how the toolbar is displayed. Each item is listed in the form of ‘drupalElementStyle', the name of the attribute, and the value of the attribute, all separated by a semi-colon. Later we will show how to display the toolbar as a list dropdown or splitbutton.

Finally, under drupal.elements we declare that this plugin can generate the data-attribution attribute on elements (which will cause the "Limit allowed HTML tags and correct faulty HTML" filter to get configured correctly!). But this plugin can't create elements, the media_media plugin can! So we make that plugin a condition for this plugin to be enabled.

And because that's the only condition we define, this plugin actually gets enabled automatically as soon as the Media (media_media) plugin is enabled.

If we save the Text Editor using the Media plugin with our new CKEditor 5 plugin available, and we then go to a form using that Text Editor, you can now see the buttons for the unknown, in-house, and external attribute in the media toolbar with their SVG icon.

After clicking on the in-house button, the data-attribution is added to the markup.

The above configuration will display as individual buttons in the toolbar because the display key is omitted. However you can also specify either display: ‘listDropdown' ordisplay: ‘splitButton' like so by changing the value of the toolbar key:

drupalMedia:
 toolbar:
 - name: 'drupalMedia:attribution'
 display: 'listDropdown'
 items:
 - 'drupalElementStyle:attribution:in-house'
 - 'drupalElementStyle:attribution:external'
 - 'drupalElementStyle:attribution:none'
 defaultItem: 'drupalElementStyle:attribution:in-house'

Thanks to the new DrupalElementStyle plugin, you can add your own custom styling to the media toolbar without a single line of JS.

Check out this blog post by @hugronaphor https://cornel.co/article/extend-drupalmedia-ckeditor5-plugin-additional-configurations for another example and special thanks to Wim Leers for helping with this blog post.