Skip to main content

Blog Post

A Comparison of D7 Image Caption Methods using WYSIWYG

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

CKEditor&#039;s Image2 plugin modal
Image2’s replacement of default Image modal

Image2 Plugin nicely formats the caption with the image inside the WYSIWYG
What image caption looks like in WYSIWYG with Image2 plugin

Image2 plugin is not formatted in node view.  This must be added.
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>

Image shows switching to source view to use caption filter
Using caption filter requires working in Source view or disabling the WYSIWYG editor.

Image shows the image and caption in a wysiwyg.  The raw tokens are displayed in the WYSIWYG.
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.

Image and caption are nicely styled by default on node view
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>

Image shows the CKEditor default plugin modal - how a JCaption is added
Adding an image with alt text via the CkEditor default image plugin.

Applying a caption with JCaption - the caption is not visible in the WYSIWYG.
A view of the image in WYSIWYG editor. The caption is not visible in the editor.

Default styling of the image in node view is a simple display of the image followed by the caption underneath
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 displays without caption in the WYSIWYG when using Image Caption module

Image inserted into the WYSIWYG. Image displays without caption.

Image caption and image as shown in node view with a simple format - unstyled image with caption underneath
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="/file/8">500x400.gif</a></h2>
  <div class="contextual-links-wrapper contextual-links-processed">
    <a class="contextual-links-trigger" href="#">Configure</a>
    <ul class="contextual-links">
      <li class="file-edit first"><a href="/file/8/edit?destination=node/4">Edit</a></li>
      <li class="file-delete last"><a href="/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>

The image is added to the WYSIWYG via the media browser by choosing the caption view mode created during setup
Adding the image and caption via the media browser. Choose the view mode in the “Display as” field and set the Caption field.

The WYSIWYG with a captioned image - the caption doesn&#039;t display
Image in WYWIWYG - no caption visible.

Image in node view contains no styling - shows just an image with a caption displayed underneath
Image as seen in node view with no styling.

 

A Comparison of Captioning Modules/Methods.

Comparison matrix of captioning modules/methods.
 Image2Caption FilterJCaptionFE & View ModeImage Caption
Integrates with Media x x 
Visible in WYSIWYGxx (although without token replacement)   
Each instance of the image can have a different captionxxx x
Works with Ckeditor ImageReplaces Image pluginxx x
Easy to set upxxx x
Source view required x   
Additional notesAlso gain image centering capabilitiesNicely styled node view out of the box without additional CSSMany config options including whether to use alt text or title text for captionMost extensive set up out of all optionsRequires adding a class to the WYWIWYG’s Font Style dropdown

 

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