CKEDitor Image2 captions and alignment
CKEditor Enhanced Image2 dialog

This module is an extension to the CKEditor module.

It also supports CKEditor installed through the Wysiwyg module.

This module helps you replace the default Image plugin that comes with CKEditor with the new Enhanced Image plugin, which has support for image captions via HTML5 <figure> and <figcaption> tags, CSS class-based alignment, centering, and improved responsive resizing.

  • Supports the CKEditor or WYSIWYG API modules, as well as the Media module.
  • Provides an example make file and instructions for downloading the required CKEditor plugins and dependencies, that do not come packaged with CKEditor standard edition by default.
  • Uses the CSS-class based approach for image alignment, as opposed to the inline styles that the image2 plugin uses by default.
  • Improves responsive image support in CKEditor, by preventing the editor from adding inline height and width to the style attribute on <img> tags.

Requirements

  • Drupal 7
  • Libraries API version 2.
  • CKEditor Standard or Full version, installed in your site's libraries folder. CKEditor version 4.4 or higher is recommended.

Drupal 8

This module will not be upgraded because Drupal 8 already contains similar custom CKEditor plugin functionality for captioned and aligned images that use HTML5.

Installation

  1. Download the CKEditor Standard or Full package from CKEditor.com and place it in the sites/all/libraries folder.

  2. Download and install this module. Ensure the Libraries API and either the Wysiwyg API or the CKEditor module are also enabled and configured.

  3. Download the Enhanced Image (image2) plugin and its dependencies from the links below; be sure to download versions that are compatible with your version of CKEditor.

    The downloaded zip files should be unzipped into the sites/all/libraries/ckeditor/plugins folder.

    Note 1: although the Dialog and Clipboard plugins are also listed as dependencies on the Image2 plugin page, they already come packaged with both the Standard and Full CKEditor builds.

    Note 2: An example Drush make file has been provided with this module to facilitate this download and installation step, which may be executed from your Drupal site root to automatically download the plugins to the correct location:

    $ drush make sites/all/modules/ckeditor_image2/ckeditor_image2.make.example --no-core
    
  4. Enable the CKEditor Image2 module. Then ensure the Image2 plugin is enabled in the editor configuration in one of the following ways, depending on which module is in use:

    • Wysiwyg module: Enable both the Image and Image2 plugin (checkboxes) in the Wysiwyg profile settings. The Enhanced Image2 plugin will be used automatically to replace the original Image plugin. See notes below about proper configuration of the WYSIWYG Filter.
    • CKEditor module: Enable the Enhanced Image2 widget plugin (checkbox) under the "Editor Appearance" section of the CKEditor profile config screen.
  5. Configure your Text formats to allow img, div, figure and figcaption tags, as well as the alignment classes (align-left, align-right, align-center).

    • If your Text formats have the Limit allowed HTML tags option enabled, ensure the following tags are allowed:

      <img> <div> <figure> <figcaption>
      
    • If your Text formats have the WYSIWYG filter option enabled, in the "HTML elements and attributes" section, ensure the img, div, figure and figcaption elements are allowed and that class attributes are allowed on the img, div, and figure elements. There are a number of ways to write these rules using the valid_elements syntax. Any of these settings should work depending on how flexible/restrictive you want the rules to be:

      • One element per line, very restrictive:

        img[class]
        div[class]
        figure[class]
        figcaption
        
      • One element per line, less restrictive; class attribute possible on any element:

        @[class]
        div
        img
        figure
        figcaption
        
      • Very restrictive, condensed:

        div,img,figure[class]
        figcaption
        
      • Less restrictive, condensed:

        @[class]
        div,img,figure,figcaption
        

      Finally, in the section on "Rules for Class Names", ensure the alignment classes are whitelisted:

      align-left,align-right,align-center
      

      Or, the less restrictive:

      align-*
      

Usage

  1. Create a node and add an image inside an editor using the Image icon/button in the CKEditor toolbar.

  2. Double-click the image to popup the Image2 Properties dialog and select alignment options or enable the caption text option.

  3. The approach taken by this module adds alignment classes including align-left, align-right, or align-center to the image or figure tag as opposed to the inline style options. Example responsive layouts are also provided in ckeditor_images2.responsive.css files, which may be overridden or disabled in your theme according to your image size requirements and breakpoints.

Compatibility

The Enhanced Image module is known to work with the CKEditor module, with CKEditor installed using the WYSIWYG API module, with either the IMCE or Insert modules for inserting images into the editor.

Known Limitations

  1. Media module integration.

    The Media module is partially compatible with Image2 -- once you insert an image with the Media module right-clicking or double clicking the image does nothing: the form must be submitted and edited again before you can access the Image2 popup; the Media module popup is no longer accessible.

    With CKEditor module and Media 7.x-2.x, consider helping work out the kinks in the new Media CKEditor:

    With Media 7.x-1.x, the following patches may be necessary to get a baseline integration working, however the form must still be saved and reloaded to be able to use the Image2 properties dialog:

  2. Filtered HTML text format.

    The Filtered HTML text format provided by Drupal 7's standard installation profile is configured to "Convert line breaks into HTML" by default. This interferes with the Enhanced Image2 plugin's HTML template that adds line breaks around the <figcaption> tag resulting in extra whitespace above and below the caption text because the linebreaks are converted to <br> tags:

    <figure>
      <img>
      <br>
      <figcaption></figcaption>
      <br>
    </figure>
    

    Therefore, the following CSS rule is added to ckeditor_image2.theme.css as a workaround:

      figure > br {
        display: none;
      }
    

    This is a somewhat hacky solution, so if a pure DOM-based solution is desired, then it is best to disable the "Convert line breaks" option on all Text Formats that use CKEditor on the backend.

  3. Responsive images with height: auto !important;

    The decision was made to support responsive images in this module out of the box. However, Drupal 7 adds height and width attributes to all image tags out of the box. Furthermore there is no dependable way to target only specific images added to the page by CKEditor. Therefore, we've had to implement a workaround by leveraging a very liberal stylesheet rule that ensures the height is set to "auto" using CSS !important.

    // in ckeditor_image2.theme.css
    img {
      vertical-align: baseline;
      max-width: 100%;
      height: auto !important;  // this line can cause problems in your design
    }
    

    This is generally accepted as a bad approach to CSS coding, but in this case it could not be helped. If this general rule is affecting your design, you have three options:

    1. Adjust your theme so that it properly supports responsive images with an automatic height, everywhere. Then fix each image that absolutely must have a fixed size, eg. the site's logo, with additional !important overrides in your theme's CSS.
    2. Disable and/or override ckeditor_image2.theme.css in your theme and customize it to your needs. The file can be wholesale disabled using the following line of code in your theme's info file:

      stylesheets[all][] = ckeditor_image2.theme.css
      

      If a file with this name doesn't exist in your theme, then this line of code has the effect of disabling the module's CSS file from ever loading on your site.

    3. If frustrated by the limitations of these two options, patches are welcome: #2952487: IMG CSS within responsive file is far to generic
Supporting organizations: 
Sponsors continued development and maintenance.
Sponsored initial development.

Project information

Releases