Caption filter may not wrap images that are only aligned, not captioned

Updated: Comment #0

Problem/Motivation

In #2014895: Image captions & alignment (for inline images), we introduced aligning and captioning of images in Drupal 8 — at long last Drupal will finally ship with that!

Currently, I'm collaborating with the CKEditor developers on getting Drupal to use CKEditor 4.3, including its leap forward in image handling (which will allow us to get rid of a whole bunch of custom code). That's what's blocking #2039163: Update CKEditor library to 4.4: some upstream changes.

We — or rather, they, because they're doing all the hard work! — are very close to a patch that will solve that issue. However, in doing so, they encountered a fundamental flaw in the code that was introduced in #2014895.

The problem is this:

filter_caption always transforms <img>s into <figure><img><figcaption</figure>, as long as the image has either a data-caption or a data-align attribute.

In other words: even an aligned image will get wrapped in a figure tag, even if no caption is set. This is beneficial for the designer/themer: the same CSS handles both captioned and aligned images. If desired, (s)he can special case the "there's no caption" case, but out of the box, but that's optional. Simple.

But what about images aligned in the middle of text?

The above wraps all images that have either a caption or an alignment in a <figure> tag. Which means we turn them into block-level elements… even if they're in fact an inline image and not a block image! This results in invalid HTML, and may break styling too.

That's what we failed to see/address/support. However infrequent on most sites, there are valid use cases for aligning images. Not to mention that this is how image alignment is demonstrated/explained in many if not most tutorials.

In other words: CKEditor 4.3's image2 plugin does things correctly, filter_caption does things incorrectly, resulting both in a mismatch between what the user sees in CKEditor and what the end result looks like, as well as invalid HTML with the corresponding consequences.

Proposed resolution

The solution is simple:

1. stop filter_caption from transforming images that only have the data-align attribute into <figure><img></figure>
2. add CSS to handle left/center/right aligned images, which we can do very elegantly since we dropped IE8 support: img[data-align="(left|center|right)" { … }

Remaining tasks

None.

User interface changes

None, other than that the output of <img src="cat.jpg" data-align="right" /> will now look differently. In the third example in this screenshot, you would now see just the llama, not the gray background + border.

API changes

None.