17 Jun

Stuart Clark

Wysiwyg Fields has been one of my more ambitious ideas in the world of Drupal. It is something that I feel Drupal has needed for a very long time, and something I could not resist taking on, but at times I felt that I had bitten off more than I could chew.

As difficult as it has been to write, it has been equally as difficult to write about, but here I go; My name is Stuart Clark, and this is Wysiwyg Fields.

What is Wysiwyg Fields?

Wysiwyg Fields is an Inline field management system, a module that bridges the gap between Drupal fields and CKEditor, giving the power of Drupal’s field system via the simple usability of a CKEditor dialog.

What that means is that Wysiwyg Fields allows for any Drupal field to be embedded directly into CKEditor and behave as a native CKEditor plugin, removing unnecessary clutter from your Drupal entity forms.

So… what is Wysiwyg Fields?

Let’s look at a standard use case for Drupal; Inline image management.

The below screenshot is of the Article content type provided by a default Drupal install. It includes three fields: Tags, Body and Image.

In my experience, clients and content editors alike would take an instant disliking to this form, as it’s missing a Wysiwyg and a simple method of inserting images into the body content.

Adding a Wysiwyg is easy enough, and while most (if not all) Wysiwygs will provide an image solution, the Images live outside of the Drupal realm; They can not take advantage of Drupal’s field formatter system, not be easily re-used in content or Views, or generally utilised by any other Drupal module.

Below is the same Article content type with Wysiwyg Fields enabled and configured for the Image field.

Apart from the addition of the Wysiwyg, the other most obvious change here is that the Image field is no longer present, leaving us with a much more compact form.

But the Image field is still there, it’s just now embedded in the Wysiwyg instead of part of the page. Simply click the Image field button on the Wysiwyg and you will be presented with something like the following:

This is a standard Image field widget embedded into a CKEditor dialog with a minor difference; Formatter and Formatter settings.

Upon uploading the image, the user can choose the formatter (if multiple formatters are set up for the field) and the formatters settings (if the formatter has settings) before clicking the OK button to insert the image.

Once inserted, the field, formatter and formatter settings can all be adjusted by selecting the inserted field and re-opening the Image field dialog, or simply by double clicking on the inserted field.

The field is rendered in the Wysiwyg as per the formatter and formatter settings as it would be when viewing the article after it has been created, however in the source code view (or via a non-Wysiwyg based Text format) it is a simple Token, as seen below.

The benefit of this approach is that whether the field or formatter ever changes, the content will automatically change to reflect those changes, whereas where markup injected it would not have the same flexibility.

Is Wysiwyg Fields a Image/Media solution?

No, Wysiwyg Fields can be used as an Image or Media solution, but it is not limited to any specific type of field. It can be used with any Drupal field, be it an Image field or a Text field, an Entity reference field or a View field.

Wysiwyg Fields doesn’t focus on being the best Image or Media solution, instead I would generally use Wysiwyg Fields in conjunction with existing Image or Media solutions; If they provide a field, Wysiwyg Fields can work with it.

However, Wysiwyg Fields is the successor to a module that was intended to be an inline image solution, Wysiwyg ImageField, and it is not out of the realm of possibility that Wysiwyg ImageField may see a future where it becomes a layer on top of Wysiwyg Fields to provide a simple inline solution.

Ok, I’m convinced, how do I set it up?

Setup is (hopefully) relatively easy to do, there are really only a few steps to get it running on a fresh Drupal installation:

1. Install the module and dependencies as per standard Drupal instructions.

2. Create or update a field so that it uses the Wysiwyg field widget.

3. As per instructions provided on screen, add your Wysiwyg field button to a CKEditor profile.

That’s all it takes.

As Wysiwyg Fields is made up of many components, some of these components also require relevant setup, but Wysiwyg Fields manages this all behind the scenes as simply as possible. Primarily, Wysiwyg Fields that the Replace tokens filter is enabled on the Text formats utilised by CKEditor profiles with a Wysiwyg field button assigned.

Additional configuration

In the case that you create the field rather than change the widget of an existing field, you should have seen that there were some additional settings for the field, as seen below.

• Sub widget type
  Wysiwyg Fields defines it’s own field widget, but some field types have multiple other widgets that change the way a field acts. This field allows you to chose the sub widget that will be used within the Wysiwyg Fields wrapper widget.
   
• Sub widget settings
  These are settings specific to the fields sub widget.
   
• Label
  By default, the button and dialog on the Wysiwyg will use the field label. This field allows that value to be overridden.
   
• Icon
  Allows the customisation of the Icon which will be displayed in the Wysiwyg.
  Icons are provided by the Icon API module and any modules that defines Icon providers.
   
• Formatters
  These are the field formatters that you wish to make available to the end user for the rendering of the field output.

Sounds good, can I use it now?

Yes! As of today (the 17th of June 2015) the first stable release for Drupal 7 is available; 7.x-2.0-beta1.

You can head over to the Wysiwyg Fields project page and grab it right now.

Can I simply test it?

Why yes, you can simply test it out now, thanks to SimplyTest.me, you can spin up a test Drupal 7 site with Wysiwyg Fields already installed just by going to: http://ply.st/wysiwyg_fields

You will still need to run through the setup steps above, but as I said, it’s easy.

This is a beta?

Yes, this is a beta, and as such there may still be some outstanding issues, as well as functionality still on the todo list.

It is recommended that in using the module you keep the beta status in mind, and if you do experience any troubling behaviour, or just have suggestions for the module, let us know over at the Wysiwyg Fields issue queue.

Get it now!

Download Wyswiyg Fields 7.x-2.0-beta 1 now!

drupaldrupal planetmodule