A Comparison of Drupal 7 Image Caption Methods using WYSIWYG Module with CKEditor

I recently had the opportunity to explore popular methods of adding captions to images inside the WYSIWYG editor using the setup of WYSIWYG module with CKEditor library. Our two main criteria were Media module integration and a styled caption in the WYSIWYG editor. As I discovered, we couldn’t have both without custom coding which the budget didn’t allow for. Media module integration won out and the File Entity with View Modes method was chosen. 

The modules/methods I reviewed were:

• CKEditor’s Image2 plugin
• Caption Filter module
• JCaption module
• Image Caption module
• File entity and view modes method

These are the results of the module and method comparisons. A matrix with various properties of each is at the end of the article.

CKEditor Image2 Plugin:

Enhanced Image (Image2) is a CKEditor plugin meant to replace the ordinary image plugin. It gives captioning capabilities in addition to center alignment and click and drag resize. The easiest way to install it is to use Quiron’s sandbox project and follow the instructions given. The only deviation I needed to make was to rename the module’s directory from ckeditor_image_captions to ckeditor_image2. 

Sample output of a captioned image:

<img alt="This is alt text" height="150" src="http://placehold.it/350x150" width="350">This is my awesome image2 caption

Image2’s replacement of default Image modal

What image caption looks like in WYSIWYG with Image2 plugin

What image caption with Image2 looks like in node view by default. It could use some styling.

Caption_filter:

Caption_filter is a token replacement method of adding a caption. Captioning is achieved by adding the caption text inside of [caption][/caption] tokens in source view. For example:

[caption align=center]<img alt="This is alt text" height="150" src="http://placehold.it/350x150" width="350" />[/caption]

Sample output of a captioned image:

<div class="caption caption-center">
 <div class="caption-inner" style="width: 350px;">
   <img alt="This is alt text" height="150" src="http://placehold.it/350x150" width="350">This is my awesome caption filter caption
 </div>
</div>

Using caption filter requires working in Source view or disabling the WYSIWYG editor.

What the caption looks like in WYSIWYG. Tokens are not replaced in the editor. Caption Filter is probably best used without the use of a WYSIWYG.

Default styling of Caption Filter’s captions.

JCaption:

This image caption module uses jQuery to transform the title or alt attribute of an image to an image caption. See the JCaption module page for another comparison of the JCaption, Image Caption and Caption Filter modules.

Sample output of a captioned image:

<span class="caption none" style="width: 350px;">
 <img alt="This is my awesome alt/caption text" src="http://placehold.it/350x150">
 <p>This is my awesome alt/caption text</p>
</span>

Adding an image with alt text via the CkEditor default image plugin.

A view of the image in WYSIWYG editor. The caption is not visible in the editor.

Default styling of the image in node view

Image Caption

With the Image Caption module, an image is added with the usual CKEditor Image plugin, and the caption is added by setting a previously defined class in the Font Style’s dropdown of the WYSIWYG editor. JQuery is used to wrap the image in an html container div and then puts the image title text in a child div underneath the image.

Sample output of a captioned image:

<span class="image-caption-container image-caption-container-none" style="display: inline-block; width: 350px;">
 <img alt="" class="caption caption-processed" src="http://placehold.it/350x150" title="This is the awesome Image Caption" style="width: 350px; height: 150px;">
 <span style="display:block;" class="image-caption">This is the awesome Image Caption</span>
</span>

Image inserted into the WYSIWYG. Image displays without caption.

Image as seen with Image Caption caption in node view.

File Entity and View modes:

This method involves the most amount of setup but integrates well with the Media module. It involves adding a caption field to the image file entity, an image style, and a view mode, and configuring the image file display. A step-by-step account of this method can be found at 58 Bits.

Sample output of a captioned image:

<div class="media media-element-container media-caption"><div id="file-8" class="file file-image file-image-gif contextual-links-region">
  <h2 class="element-invisible"><a href="http://www.mediacurrent.com/file/8">500x400.gif</a></h2>
  <div class="contextual-links-wrapper contextual-links-processed">
    <a class="contextual-links-trigger" href="http://www.mediacurrent.com/">Configure</a>
    <ul class="contextual-links">
      <li class="file-edit first"><a href="http://www.mediacurrent.com/file/8/edit?destination=node/4">Edit</a></li>
      <li class="file-delete last"><a href="http://www.mediacurrent.com/file/8/delete?destination=node/4">Delete</a></li>
    </ul>
  </div>
  <div class="content">
    <img height="176" width="220" class="media-element file-caption" typeof="foaf:Image" src="http://captions.dev/sites/default/files/styles/medium/public/500x400_5.gif?itok=IsKmYwfN" alt="">
    <div class="field field-name-field-caption field-type-text field-label-hidden">
      <div class="field-items">
        <div class="field-item even">This is the awesome File Entity caption</div>
      </div>
    </div>
  </div>
</div>

Adding the image and caption via the media browser. Choose the view mode in the “Display as” field and set the Caption field.

Image in WYWIWYG - no caption visible.

Image as seen in node view with no styling.

A Comparison of Captioning Modules/Methods.

Summary: Which Module Do I Use?!?

Which module is used is really dependent on the requirements of the project. If you require Media module functionality (maintaining a library of images that can be searched and re-used), the only two options are the File Entity - View Mode method and the Caption Filter module. If your editors are savvy and understand html basics, Caption Filter will give you more flexibility around captions, allowing you to reuse images with different captions tailored to the context. If you need to keep it as simple as possible, doing the extra work of setting up the File Entity and View Modes will make it pretty simple for your editors to add pictures, have them automatically resized, and aligned without any additional work.

If the Media module is not needed, Image2, JCaption, and Image Caption are all pretty comparable, although I would lean towards the Image2 plugin simply because it gives the ability to center the image and the caption is visible in the WYSIWYG editor. The one thing I would caution against is in the JCaption module. It gives the option of using either alternative text* or title text as the caption. It’s generally not good practice to simply duplicate the alt text (you are adding alt text to your images, right?) for a caption. Both the caption and the alt text will be read by screen readers and will be redundant for the user. Using title text as caption text may be less problematic since most screen readers do not read title text by default.

*Alternative text (or alt text) is text that describes an image. It gives people who are blind and use screen readers and people who have images turned off due to low bandwidth a description of the image that they can’t see. It is good practice to include alt text for images.

Additional Resources

Guide to Drupal Terminology | Mediacurrent Blog post
Conditionally Open a Link in a New Tab in Views Without the PHP Filter | Mediacurrent Blog Post