Matt Glaman: Drupal module semantic versioning for Drupal core support

A large amount of our time during the Drupal 10 readiness effort was around semantic version discussions. Folks were creating new major versions to add Drupal 10 support while dropping Drupal 9 simultaneously. Technically that follows the semantic versioning guidelines but is a horrible user experience. Users must update the module when they upgrade Drupal core to Drupal 10. Ideally, users could update their modules first and then upgrade Drupal core.

This blog post is taken from part of my talk "Lessons learned from helping port the top contrib projects to Drupal 10." It is also inspired by my coworker Jakob Perry's blog post, "Don’t go making major version changes."

Evolving Web: Porting a CKEditor 5 Plugin to Drupal 10

Image removed.Introduction

CKEditor 5 was introduced in Drupal 9.3 and is now the default WYSIWYG editor in Drupal 10. It’s no mere update on its predecessor – in fact, CKEditor 5 was written completely from scratch. 

The good news is that Drupal 10 users get a completely overhauled content editing experience. CKEditor 5’s features include a vastly improved user interface and premium collaboration tools. 

But there’s some groundwork to be done first. Due to their considerable differences, you can’t simply reuse CKEditor 4 code with CKEditor 5. 

Some third-party plugins have already been ported to CKEditor 5. But their implementation is different and you’ll need to rewrite any custom code you developed for CKEditor 4. 

Our developers at Evolving Web created this guide to make the implementation process easier for you. We’ve used the plugin ckeditor5-anchor as an example. Below, you’ll find step-by-step instructions with code for integrating the anchor plugin with Drupal.

Code Examples

The ckeditor5_dev module is shipped with a handy starting template. This is based on the Block Widget plugin from the CKEditor 5 documentation: Implementing a block widget.

Also check out this list of contrib modules that provide CKEditor 5 plugins, such as ckeditor_accordion.

Step 1: Create a Custom Module

Let’s name the module ckeditor5_anchor. The module should not contain any PHP code. Aside from the info.yml file, the module will include the following.

Ckeditor5_anchor.ckeditor5.yml

ckeditor5_anchor_anchor: ckeditor5: plugins: - anchor.Anchor drupal: label: CKEditor5 Anchor library: ckeditor5_anchor/anchor admin_library: ckeditor5_anchor/anchor.admin toolbar_items: Anchor: label: Anchor elements: -

Note that library is the plugin code itself. In our case, admin_library is CSS to be applied on the text format configuration page. CKEditor provides more details about the file structure.

ckeditor5_anchor.libraries.yml

anchor: remote: https://github.com/bvedad/ckeditor5-anchor version: "1.0.0" license: name: GNU-GPL-2.0-or-later url: https://github.com/ckeditor/ckeditor5/blob/master/LICENSE.md gpl-compatible: true js: js/build/anchor.js: { preprocess: false, minified: true } css: theme: css/anchoractions.css: { } css/anchor.css: { } css/anchorform.css: { } css/anchorimage.css: { } dependencies: - core/ckeditor5 anchor.admin: css: theme: css/anchor.admin.css: { }

The anchor library contains:

  • js/build/anchor.js which is the plugin code.
  • CSS files are taken from the plugin source. For some reason, CSS files for this particular plugin are actually SCSS files with .css extension. You’ll need to convert them to true .css files.

package.json. 

Copy it from the CKEditor 5 plugin starter template.

{ "name": "drupal-ckeditor5-anchor", "version": "1.0.0", "description": "Drupal CKEditor5 Anchor plugin", "author": "", "license": "GPL-2.0-or-later", "scripts": { "watch": "webpack --mode development --watch", "build": "webpack" }, "devDependencies": { "@ckeditor/ckeditor5-dev-utils": "^30.0.0", "ckeditor5": "~34.1.0", "raw-loader": "^4.0.2", "terser-webpack-plugin": "^5.2.0", "webpack": "^5.51.1", "webpack-cli": "^4.4.0" }, "dependencies": { "@ckeditor/ckeditor5-core": "^36.0.1", "@ckeditor/ckeditor5-image": "^36.0.1" } }

In our case, we also needed @ckeditor/ckeditor5-core and @ckeditor/ckeditor5-image. Pay attention to the webpack hints when compiling js/build/anchor.js. 

webpack.config.js. 

Copy it from the CKEditor 5 plugin starter template. Both of CKEditor’s documentation examples use webpack, although you may decide to use another tool to pack your javascript code.

Create the following folders:

  • ckeditor5_anchor/js/build for your minified plugin code.
  • ckeditor5_anchor/js/ckeditor5_plugins/anchor for the source JS code.
  • ckeditor5_anchor/css
  • ckeditor5_anchor/icons
Step 2: Get the Source Plugin Code

Clone the plugin source code somewhere outside of your site.

gh repo clonebvedad/ckeditor5-anchor

Copy ./src and ./lang folders into ckeditor5_anchor/js/ckeditor5_plugins/anchor.

Copy CSS and icon files into ckeditor5_anchor/css and ckeditor5_anchor/icons respectively. They’re located in the ./theme folder for the anchor plugin.

Step 3: Install the Dependencies npm install

Generate js/build/anchor.js.

./node_modules/.bin/webpack --mode development --watch

At this stage, you will likely encounter missing dependencies warnings.

Step 4: Modify the source code

Add ckeditor5_anchor/js/ckeditor5_plugins/anchor/src/index.js

/** * @file The build process always expects an index.js file. Anything exported * here will be recognized by CKEditor 5 as an available plugin. Multiple * plugins can be exported in this one file. * * I.e. this file's purpose is to make plugin(s) discoverable. */ import Anchor from './anchor'; export default { Anchor, };

We need to modify the import section to import all CKEditor libraries from one of the files under ckeditor5/src/ (ckeditor5_achor/node_modules/ckeditor5/src/). For example:

-import Plugin from '@ckeditor/ckeditor5-core/src/plugin'; -import MouseObserver from '@ckeditor/ckeditor5-engine/src/view/observer/mouseobserver'; -import Clipboard from '@ckeditor/ckeditor5-clipboard/src/clipboard'; -import Command from '@ckeditor/ckeditor5-core/src/command'; -import findAttributeRange from '@ckeditor/ckeditor5-typing/src/utils/findattributerange'; -import toMap from '@ckeditor/ckeditor5-utils/src/tomap'; -import Collection from '@ckeditor/ckeditor5-utils/src/collection'; -import first from '@ckeditor/ckeditor5-utils/src/first'; -import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview'; +import { Plugin } from 'ckeditor5/src/core'; +import { MouseObserver } from 'ckeditor5/src/engine'; +import { Clipboard } from 'ckeditor5/src/clipboard'; +import { Command } from 'ckeditor5/src/core'; +import { findAttributeRange } from 'ckeditor5/src/typing'; +import { toMap, Collection, first } from "ckeditor5/src/utils"; +import { ButtonView } from 'ckeditor5/src/ui';

Import icons shipped with the source plugin from the right Drupal module path. 

-import anchorIcon from '../theme/icons/anchor.svg'; +import anchorIcon from '../../../../icons/anchor.svg';

Replace importing all icons loaded from the CKEditor core @ckeditor/ckeditor5-core with import { icons } from ckeditor5/src/core.

-import pencilIcon from '@ckeditor/ckeditor5-core/theme/icons/pencil.svg'; +import { icons } from 'ckeditor5/src/core';

Use the icons variable in the code where an icon is used.

-this.editButtonView = this._createButton( t( 'Edit anchor' ), pencilIcon, 'edit' ); +this.editButtonView = this._createButton( t( 'Edit anchor' ), icons.pencil, 'edit' );

Almost there! One more change is needed specifically for ckeditor5-anchor

function isTyping( editor ) { - const input = editor.plugins.get( 'Input' ); - - return input.isInput( editor.model.change( writer => writer.batch ) ); + const batch = editor.model.change( writer => writer.batch ); + return batch.isTyping; }

Note that the source plugin uses an outdated method. Input.isInput was replaced with batch flags. It’s important to expect these issues and always QA your CKEditor5 plugins after porting them.

Additional Notes
  • anchor.admin library contains a CSS file: ckeditor5_anchor/css/anchor.admin.css. 
/* Icons */ .ckeditor5-toolbar-button-Anchor { background-image: url(../icons/anchor.svg); }

This icon is to be displayed on the text format configuration page.

  • You can migrate CKEditor4 plugin settings to a new CKEditor5 plugin using \Drupal\ckeditor5\Annotation\CKEditor4To5Upgrade. Refer to examples in the core.
Useful Resources

CKEditor Documentation 

We’d recommend reading all of the tutorials available in CKEditor 5 Framework documentation. You can safely skip the editor init part as Drupal already inits the editor for you. 

In particular, read up on Drupal’s slightly different way of importing JS dependencies as well as icons:

Drupal Documentation

Useful pages from drupal.org include:

+ more awesome articles by Evolving Web

Specbee: How to Setup a Drupal Site on Pantheon from Scratch

How to Setup a Drupal Site on Pantheon from Scratch Karishma 02 May, 2023 Subscribe to our Newsletter Now Subscribe Leave this field blank

Did you know Pantheon is one of the largest hosting providers for Drupal websites the world over? As of 2021, they host over 300,000 Drupal sites*! Launched in 2010, Pantheon offered Drupal-specific hosting environment that was optimized for Drupal websites. As a website management platform, they offer an integrated set of services and tools allowing teams to build, launch, and manage websites. 

Drupal and Pantheon are a great match. Find out more about this as you read on AND also learn how to install Drupal on Pantheon from scratch. There’s more! You will also find out about setting up Pantheon locally, interesting commands for transfers, command line interactions and more. Dive in!

Image removed.

Why do Drupal developers Love Pantheon

Drupal developers prefer Pantheon because it is easy to use and set up, but more importantly because it offers an environment optimized for Drupal sites. Even the security features are specifically tailored to the needs of Drupal websites. A few more reasons why Pantheon is a great choice for developers:

  • Automated backups, security monitoring and Automated updates.
  • Website Performance Monitoring using New Relic
  • Git and Version control on all domains
  • Redis and Varnish cache to speed-up page delivery by caching
  • Multi-dev environment to easily keep track of code changes
  • Highly responsive Pantheon support team to help work through server related issues and technical issues.

Setting Up Drupal on Pantheon

It really is a very straightforward process. Follow the steps below to setup Drupal 9 on Pantheon

1. Visit https://pantheon.io/ to register to Pantheon using your email address

2. Click on Get Started

Image removed.

3. Once logged in, you will be land on the workspace page

4. Click on Create New Site as shown below.

Image removed.

 

5. Choose what kind of site you want to create. Let’s go with Drupal 9. Read this article to find out why.

Image removed.

 

6. Provide your Pantheon site details like the Name of the Site and continue.

Image removed.

 

7. This process will take a few moments. Once it's done, click on “Visit Pantheon Site Dashboard.”

Image removed.

 

8. Visit your website, by clicking “Visit Development Site”.

Image removed.

Installing and Customizing your Drupal 9 site

Now that you have set up Drupal on Pantheon, let’s install and customize your Drupal site. Upon visiting your website for the first time, you will be directed to the Drupal installation page.

  • Choose the language of your choice. I’ll go with English.
  • Choose the Standard Installation profile. 
Image removed.

 

  • Configure your site with information like Name of the site, Site Email Address, Username and password.
  • Hit Save.
Image removed.

 

And your Drupal 9 site is ready!

Image removed.

Setting Up Pantheon Locally

Using the following commands to set up Pantheon on your local system:

Create a new directory “pantheon” and enter it
mkdir pantheon && cd pantheon

Go through interactive prompts to get your site from Pantheon and create a .lando.yml file
lando init 

Start up the application
lando start

Import your database and files
lando pull

Transfering Files with the Get and Put Command

The Get and Put commands help create a file transfer request in SFTP.

  • First, login to the server using the SFTP command provided in Connection Info
Image removed.

 

  • If you’re logging in for the first time, you need to generate machine tokens to uniquely identify your machine and securely authenticate yourself. Find out how to generate machine token here.
Image removed.

 

Use the GET command to transfer files from a remote server to your local system

get
get -r

Use the PUT command to transfer files from your local system to the remote server

put
put -r

Terminus Command Line Tool

Terminus is a command-line interface (CLI) provided by Pantheon, which allows you to manage Drupal sites using a set of powerful tools. It is built on top of the Drush command-line tool, and provides additional functionality that is specific to Pantheon.

Developers can manage their Drupal sites from the command line, without the need to use the Pantheon dashboard.

To install Terminus, go here: https://docs.pantheon.io/terminus/install

Format of the terminus command: terminus command:subcommand .

The terminus command structure includes . in order to determine the target site and environment to execute the command.

For example, running the clear cache command for the Dev environment of a site labeled "techxspecbee"

Image removed.

 

To run the configuration import drush cim command for the Live environment of a site labeled "techxspecbee"

Image removed.

 

We can get a list of all available commands using

Image removed.

 

Image removed.

 

* References: https://www.drupal.org/pantheon

Drupal provides a robust content management system that is flexible and highly customizable, while Pantheon provides a secure and scalable hosting platform that is optimized for Drupal sites. The combination of Drupal and Pantheon allows developers to build websites quickly and easily, while also ensuring that they are secure and performant. With features like automatic backups, continuous integration, and easy site management, Pantheon is a great platform for Drupal developers looking to build websites that can scale with their projects. Are you looking for Drupal experts to build and manage your Pantheon-hosted site? We’d love to  help! Contact us today and let’s get started.

Email Address Subscribe Leave this field blank Drupal Drupal 9 Drupal Development Drupal Planet Drupal Tutorial

Leave us a Comment

 

Recent Blogs

Image Image removed.

How to Setup a Drupal Site on Pantheon from Scratch

Image Image removed.

Understanding Update and Post Update Hooks for Successful Drupal Site Updates

Image Image removed.

Embracing Achievements - Gagana Girish’s Living Dream

Want to extract the maximum out of Drupal? TALK TO US

Featured Case Studies

Image removed.Image removed.

Upgrading the web presence of IEEE Information Theory Society, the most trusted voice for advanced technology

Explore
Image removed.Image removed.

A Drupal powered multi-site, multi-lingual platform to enable a unified user experience at SEMI

Explore
Image removed.Image removed.

Great Southern Homes, one of the fastest growing home builders in the US, sees greater results with Drupal

Explore
View all Case Studies

LN Webworks: How Can Drupal Make Online Marketing Easy

Image removed.

Drupal has been the most advanced and preferred online marketing and content management system for years now. Prestigious websites such as NASA, Tesla, Oxford University, Virgin, and General Motors have unleashed the power of Drupal to excel in their respective domains.

Simple content authoring tools, built-in accessibility tools, multilingual functionality, seamless integration with third-party tools and services, cutting-edge security features, and open-source licensing are some Drupal features that have helped it supersede all its competitors. Besides, its top-notch SEO-friendly modules have made multitudinous websites earn first-page rankings on search engines. This has brought significant increments in their customer reach, acquisition, and retention. Their revenue has also escalated manifolds. Isn’t it fascinating?

mandclu: A Major Step Forward for Smart Date

A Major Step Forward for Smart Date Image removed.mandclu Tue, 05/02/2023 - 06:10 The planning for a 4.0 release of Smart Date began towards the end of 2021, but there were still lots of opportunities to fix bugs and add features without going to a major release. In the end, the need for a major release was triggered by Drupal 10, though in actuality by its updated PHP dependency, to use a minimum version of 8.1.Smart Date had made some methods available to be used statically, that is, for the method to be used without instantiating a full object. This was a useful way to make capabilities available broadly, and drew inspiration from Drupal core static methods like Entity::create() or Url::fromRoute(). Newer versions of PHP, and in particular 8.1, are much more stringent about mixing static and non-static code. Calling non-static methods within a static one can generateMore

LN Webworks: List of United Nations and World Bank Websites Using Drupal

Image removed.

Did you know that out of the 117 domains of the UN and World Bank organizations, 78 rely on Drupal? Seems fascinating, doesn’t it? With its ingenious features, Drupal validated its worth and earned the trust of a majority of the prestigious organizations in the world. It established itself as the leading content management system long ago and continues to maintain its stature even today. If you are getting inclined towards Drupal Web Services too, you might wish to analyze the websites it already supports to make an informed decision.

Talking Drupal: Talking Drupal #397 - Semantic Versioning

Today we are talking about Semantic Versioning with Mike Miles.

For show notes visit: www.talkingDrupal.com/397

Topics
  • What is Semantic Versioning
  • Why is it important
  • How does Drupal 8 map to Semantic Versioning
    • 8.x
  • What about betas, alphas, rcs
  • How does it help dev teams stay organized
  • When did you start thinking about Semantic Versioning
  • Talk at NERD Summit
  • Benefits of Semantic Versioning
  • Other than the basics, how does your team use Semantic Versioning
  • How do you move existing projects over to Semantic Versioning
  • If someone wants to start using Semantic Versioning where should they look
Resources Guests

Mike Miles - mike-miles.com @mikemiles86

Hosts

Nic Laflin - www.nLighteneddevelopment.com @nicxvan John Picozzi - www.epam.com @johnpicozzi Jordan Graham - @jordanlgraham

MOTW Correspondent

Martin Anderson-Clutz - @mandclu Same Page Preview Shows your content authors what their content will look like, while they’re creating it.