CKEditor

Adding Custom Styles and Classes to Your WYSIWYG

Mediacurrent Team — Thu, 25 Feb 2016 19:13:14 +0000

Adding Custom Styles and Classes to Your WYSIWYG

More and more these days, we need to add custom styles to content that the user enters. This can be a challenge for front end developers as we don't know how the information will be entered and have less control over the structure. One thing we can do to help content editors is to provide them with classes and styles based on these classes that they can add in the WYSIWYG.

As this is not a how to set up a WYSIWYG tutorial, I will just state that we use CKEditor.

Once CKEditor is installed, you can begin configuring it and adding your own styles and functionality.

The config page allows you to choose the CKEditor mode that you want to customize. In this example, I am editing the 'full' profile.

Config page:

https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_config.html

The tab we are interested in is 'CSS'.

The first configuration that we want to make is to 'Editor CSS'. As the help text suggests, this allows you to add specific css for the editor. This is what the person who inputs content will see on the admin page. Because we rename our css file, we need to use the Define CSS option.

We need to define the path. The help text suggests several shortcut methods. This is how to use the theme path, which is what you will most often use.

The field input is: %tcss/ckeditorstyles.css. In this case our css is inside ThemeFolder/css. Note that there is no forward slash between the %t and the css subfolder.

In this example I have a separate stylesheet that relates to items in the WYSIWYG. However you could link to your main.styles.css sheet, or any style sheet that you define these styles in. I chose to make a smaller style sheet so I wasn't loading a large sheet that was mostly unused.

The next configuration we are going to make is to the Predefined Styles. As with the css we want to define the path to the file. The helper text says:

'CKEditor is highly configurable. The most commonly used features are listed below. You can also adjust CKEditor to your needs by changing the ./sites/all/modules/contrib/ckeditor/ckeditor.config.js configuration file.'

This is what we want to do, so we are going to copy this file, and move it to our theme js folder. Once we have done that we can enter its location in the Predefined styles path. As with the css path, we want the format to be %tjs/ckeditor.styles.js or whatever your structure. The important part again being no leading / before the subfolder.

Now we have set up our custom paths, and have either moved or created the custom files, we can add our new styles. If you open the 'ckeditor.config.js' file we copied, you can see that the styles are fairly well documented, if not weirdly spaced. I won't explain what is documented in the file, but it should be clear how to add new classes and elements to your set up.

What should you do when your changes don't appear?
So this happens a lot and is the main reason I wanted to write this as you can lose hours trying to figure out why the additions you have made do not appear.

The first thing to do is to make sure that the settings in the config are mapping to the correct files. By this, I mean that you are pointing the custom settings to the corresponding files in your theme.

You can check in the DOM, or use the Network tab in the inspector, to see if the custom css file is being called. The next check is to make sure that the WYSIWYG is in the same mode as the one that you added the custom settings to. In my example, I used 'full'. The setting for this is on the content piece you are editing here:

If you are seeing some of your custom styles that are defined in the js file in the editor but not all, there are several things that you can check. First, is the editor set up to allow the tag that you are defining? Second, if you added the style as a button to the editor, does the editor have that button? These can be checked here, on the CKEditor config page, under Editor Appearance:

What if edits to your js file are not showing up?

This is the most common issue that I have had. First, I would recommend trying to get as many edits done in between testing as possible. Obviously that isn't that easy to do, and you will always have to make changes, but it is useful to think in terms of making as few updates as possible. The reason for this is that the module seems to either cache or use a timestamp for the custom js file that is hard to break. One work around I had locally was that for every time I made changes to create a copy of the file, and move it to a subfolder, and then reference that in the config settings. As this is the first time that the file has been called you can see the changes.

My workflow for this was to make the changes to the file at themename/js/ckeditor.styles.js. Then create a tmp folder in js and copy the file to it, example themename/js/tmp/a/ckeditor.styles.js . Then go to admin/config/content/ckeditor/edit/(mode) and add the new path %tjs/tmp/a/ckeditor.styles.js. Clear caches and enjoy the new styles.

I hope this helps you, I know the information is out there, but I had to look in several places so hopefully, this will shorten your search.

My Sources
CKEditor - WYSIWYG HTML editor
Drupal 7: Installation of CKEditor vs. CKEditor and WYSIWYG

Mediacurrent Team Thu, 02/25/2016 - 14:13

A Comparison of D7 Image Caption Methods using WYSIWYG

Mediacurrent Team — Tue, 24 Mar 2015 17:18:09 +0000

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

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="/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>

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.

Comparison matrix of captioning modules/methods.
	Image2	Caption Filter	JCaption	FE & View Mode	Image Caption
Integrates with Media		x		x
Visible in WYSIWYG	x	x (although without token replacement)
Each instance of the image can have a different caption	x	x	x		x
Works with Ckeditor Image	Replaces Image plugin	x	x		x
Easy to set up	x	x	x		x
Source view required		x
Additional notes	Also gain image centering capabilities	Nicely styled node view out of the box without additional CSS	Many config options including whether to use alt text or title text for caption	Most extensive set up out of all options	Requires 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.

Mediacurrent Team Tue, 03/24/2015 - 13:18