Image captions & alignment

Problem/Motivation

We finally have a WYSIWYG editor in core: #1890502: WYSIWYG: Add CKEditor module to core.

If we can now also add image captions, align images, and align the caption along with the image, then we'll finally have achieved what quicksketch has been asking for years :)

As usual, we want our content to remain pristine and not contain crappy markup. It should not prevent structured content. Hence it should be a filter.

Furthermore, it should be possible for a site to 1) customize the HTML & CSS used for the captions across the entire site, 2) do 1 after content was created. Using a filter addresses those two requirements as well.

Finally, disabling this filter on a text format should cause the content to not be broken; it should gracefully degrade to just images. Which means custom syntax like this is unacceptable: [caption]<img src="" alt="" />This is an image caption[/caption]. That is: the content stored in the DB must remain clean, it must remain HTML.

Proposed resolution

All of the above requirements are met by enriching <img> tags with data- attributes:

<img src="cat.jpg" data-caption="Caption text." data-align="(left|right|center)" />

This is then transformed to something like this by theme_filter_caption() (this is the HTML that the caption_filter module uses, and it's been proven in real-world testing):

Note: the generated HTML does not actually matter, we could also change it to something more modern/HTML5y and less infected by divitis:

(Based on http://alistapart.com/blog/post/more-thoughts-about-blockquotes-than-are....)

Let's figure out what's the best caption markup for Drupal core.

UX to caption & align images

We will make it trivial for CKEditor users to do this, and will even make it a delightful experience. However, this is the necessary first step, which obviously works stand-alone.

Origin of code

The code to do this was partially lifted from the http://drupal.org/project/caption_filter module: the generated HTML and corresponding CSS is unchanged from that in that module. The code that takes care of the filtering has been revamped to be much more robust though: much like the filter_html_image_secure filter, this uses PHP's DOMDocument/DOMNode APIs to do this in a much more robust manner.

(This is exactly what was built for Aloha Editor back in October 2012; in fact, I copied the code I wrote for this from aloha.module. The code was stable/solid then, and it is now.)

Remaining tasks

1. Build consensus:
   1. Implemented as filter?
   2. Part of filter.module?
   3. Target HTML?
   4. Filter enabled by default for Basic HTML and Full HTML in Standard profile?
2. Test coverage.
3. Integrate this with CKEditor: make it a trivial, delightful experience to caption and align images!

User interface changes

• New filter_caption filter.
• Image captions in Drupal core!
• Filter enabled by default for Basic HTML and Full HTML in Standard profile.
• No UI to caption or align images! This is about the filter only, there will be a separate issue for CKEditor integration.

API changes

None, unless a new theme function counts.

Related Issues

Soon, an issue for: "Integrate this with CKEditor: make it a trivial, delightful experience to caption and align images!".