Better than WYSIWYG? The BUEditor in Drupal 7: Use and Configuration

Some time back, I promised another short article in the WYSIWYG set-up series for Drupal 7, one which covers BUEditor. First, we should note that the BUEditor is not actually “WYSIWYG”, but it offers some nice features which might make it a bit better than the WYSIWYG options, depending on your use case. It also does not integrate with the Wysiwyg module. You add it separately (and instead of Wysiwyg), but it does have some great supporting modules and code libraries. This article covers some of the basics about use and installation of the BUEditor on a Drupal 7 site (most of the information applies equally to Drupal 6, where the BUEditor module is also available). I’ve also got some good tips for some ways to extend the default button-set. (And you can download my modified button code here to easily import the buttons into a new editor profile.)

The BUEditor is now used on Drupal.org

Since the time I planned to write this post, BUEditor has surely got some additional attention; it’s now what you’ll use if you leave a comment on an issue or forum post on Drupal.org. It’s refreshing to have more than just a plain text area for HTML entry; I think this is a great step for the Drupal community’s official site. In addition to basic set-up of the BUEditor, as it’s used on Drupal.org, I’d like to cover some nice features of the BUEditor which are not being used on Drupal.org.

The BUEditor integrates nicely with IMCE

The most recent article in this series covered the set-up of IMCE and supporting modules for inserting images. You’ll be glad to know that the BUEditor supports adding images with IMCE. I’m sure you could also simply “attach” images and add them to content with the Insert module. The BUEditor’s default image popup is very limited, which was at first a deal-breaker for me to suggest using it on this website, however I learned it’s not so difficult to adjust the pop-up dialog to add more fields; by default it only has the URL, dimensions, and alt text fields. I also wanted fields for title text, class, and style (though it is probably best to avoid using inline styling, it’s sometimes handy and nice to have a GUI for adding this to your tag when you create it).

Remaining downsides to the image dialogue

Proportional dimension calculations: It would be nice if there were support for automatic adjustment of the “Width” and “Height” fields to adjust one automatically (by ratio) if the other is modified. I tend to place images that are often wider than 600 pixels, which means they would not display nicely in the layout of this site. The Image Resize Filter automatically creates a smaller image, to be displayed in the content, if I adjust the size when placing the image. And it’s easy to link the full-size original image to appear in either a Lightbox2 or Colorbox overlay. If I have an image which is 938 pixels wide by 529 pixels high, and I change “Width” to 600 in the BUEditor image popup, I’d like a default option for the “Height” to automatically be proportionally re-scaled, as it works in CKEditor and TinyMCE. It’s not hard to calculate what the height should be, but I’d rather not have to, and I’m not the only one who would have to. The easy solution to this is to just leave the height field empty and the Image Resize Filter will still proportionally resize the image, but if the image doesn’t load, for some reason, the page layout will be affected.

Longer fields: Even after working out how to add the new fields, I couldn't figure out how to make the whole dialogue larger (assuming physical display size is large enough) so that these fields could all be a bit wider. The default size of the text fields is pretty darn short, but my initial attempts to modify this just ended up breaking the whole editor. Well, it’s not a big deal, but perhaps I'll figure out how to further customize the image pop-up. (If anyone knows how to make such modifications through simple button code (or an add-on module), please share your tips.)

Quibbles aside, the BUEditor really is awesome!

The BUEditor provides a nice, clean user interface with what could be a perfect balance between simplicity and usefulness, provided users are comfortable with working directly with HTML code. It’s easy to apply formatting to selected text and it’s also simple to modify the values of the editor buttons or add your own. Converting unstyled lines of text into lists (ordered or unordered), blockquote, or heading, is as simple as the click of a button and if anything gets mucked up, you have the code right there to adjust, but it’s less likely to get messy than with a WYSIWYG editor since you have complete control over what you select before you click the button. This might be a good time to mention that there is also a Drupal-free version of the BUEditor, though the BUEditor was first created specially for Drupal, unlike so many of those other (“WYSIWYG”) editors.

It’s especially awesome with the Ajax Preview option enabled

The Ajax markup module, also written by the author of the BUEditor, allows you to simply modify the “Preview” button to provide a display which closely matches the end result (taking the text format settings into consideration). Awesome! I’d like to see them add this integration on Drupal.org, too, since it’s much faster and nicer than reloading the page with the main “Preview” button. It would be great to also have this functionality in a Wysiwyg-integrated editor. Bear in mind, once you have this configured and working, clicking the “Preview” button displays the preview and by dragging on the handle at the bottom of the editor pane, you can see the corresponding code… but you won't be able to edit that code till you click the “Preview” button again.

BUEditor keyboard shortcut support

Not all browsers support the shortcuts equally, but when you are actively using the text editor, you should be able to use keyboard shortcuts to add tags, snippets you’ve configured, or perform other editor functions. In Safari, I found that I had to use the control and option keys in combination with the configured key. In Firefox it was just the control key. More than one editor in a page can mess this up and the shortcuts may not work at all in some browsers, but they can certainly be useful. You can also remove the key codes if you think it might cause more problems for your users than it’s worth.

Keep in mind: The button-set is based on role

One potential issue is that the editor button set is based on the user role, not on the Text format. So it’s still easy to create content (as a privileged user) in the “Filtered HTML” format, and include images or other tags… that are then stripped on output. With Wysiwyg-integrated editors, the button sets are per text format. There are pros and cons to this, but I’d prefer to have a default editor configuration for each text format. There is a BUEditor Plus add-on module which aims to take care of this issue, but it’s still in beta (actually still in the developer’s “sandbox”). Since it’s likely to be released soon as a full project, I won’t link to the sandbox. Instead look for the module on HollyIT’s user page on Drupal.org. Caveat: I can not confirm that the sandbox beta is ready for production use. Use or experiment at your own risk.

Another cool feature: BUEditor supports BBCode output

Many forums and sites support BBCode, which is easier for users to enter, a bit simpler than HTML, and removes many of the potential hazards of allowing users to enter HTML. If you want to have commenters post using BBCode, it’s as simple as configuring the button-set for the included BBCode editor. The defaults might already be everything you need. Of course you’ll also have to add and enable a BBCode text filter.

Are you ready to install and configure the BUEditor?

Add and activate the modules

admin/modules
You will want to download the appropriate modules. The BUEditor module is required, of course, and I also recommend the Ajax markup module. Add them both to your sites/all/modules folder, then activate them, as usual. If you want to use IMCE, IMCE Mkdir, and/or the Image Resize Filter, be sure to add and activate them, too (see previous lesson about using IMCE with images in a Wysiwyg-integrated module and just follow the steps for configuring IMCE and the Image Resize Filter.)

Note: The BUEditor Plus module is also shown here, but may not yet be ready for production use. And, in case you were wondering, Internal links is a module I’m working on in my free time, so you see an “unversioned” copy in the screenshot from my D7 development installation. I will be committing some improvements to that in the near future.

Configure the BUEditor

admin/config/content/bueditor
Click the “Import editor” link to easily start from exported button code, like the modified button-set I’ve attached here. By the way, I’ve tested this button code in both BUEditor 6.x-2.x and 7.x versions. The same button definitions work in both.

To import a previously exported button-set, paste the code in the “Editor code” text area

You can create a new editor based on the Default profile (as I did originally) or you can import the code I’ve already modified to provide what might be a better starting point. Simply add a name for your new editor and paste the code from that file into the text area labeled “Editor code (PHP)”

If you choose to start from the “Default” set, and want to enable Ajax preview, look for the “Preview” button in the “Buttons” rows and paste over the existing “Content” for that button with the following code:
js: E.prvAjax();

Note: This is already done in the attached version of the button-code.

Another change I made was to remove the “Heading1” selector from the default Headings button code. Why? A page should really only have one <h1> tag, and it’s already provided by the node’s Title field, so except in unusual use cases, you’d never want to have this in your editor. That tag can be removed from the button very simply by dragging the “Content” text area for Headings open to see the full contents and selecting the second line for deletion. I also added a few new text buttons for <p>, <br />, and <?php tags; adding or customizing such tags is super-easy, especially if you simply add a plain text “Icon” to represent the button in the editor, as I did. If you want to add custom icons, you can supply the path to find your custom icons (e.g. a copy of the default icons, plus a few more that you create yourself; or you could replace the original icons with ones you like better. The original icons are all 20 pixels high, so match the height and your icons should look fine; for my paragraph and line-break buttons, a plain-text button suits me, but I’ve created a few alternate icons, included with the attached code.) If you choose to use alternate or extra icons, be sure to follow the directions included in the readme.txt file within the BUEditor module’s “icons” subfolder and copy all default and custom icons that you want to use to a new sub-directory under your files path.

Additional simple toolbar configurations

You can drag rows up and down to adjust the order of icons in the BUEditor toolbar. You can also modify the keyboard shortcuts linked to the buttons and make other simple modifications before saving. I would suggest that you actually save periodically and make sure that everything is still working in the “Demo” text area, especially if you are editing button code or adding new buttons.

It’s a good idea to periodically select all buttons and export your button set. To export all buttons, simply select the checkbox at the top right of the “Buttons” configuration table, which will select all checkboxes, then at the bottom of the list, select the “Export” action and click “Go”. You can also use this action selector to remove buttons with the “Delete”, copy selected buttons to another configuration of BUEditor, etc. If you don't do this, you might not notice when your custom code gets broken until you just have no icons showing up above the Demo textarea after clicking Save configuration. If you’ve got the buttons backed up, you can easily revert to a working set.

Assign the new editor(s) to suitable role(s)

admin/config/content/bueditor
Be sure to go back to the main BUEditor configuration page and select your new editor configuration to use for the appropriate roles. In this case, the “advanced” editor I set up for “Staff” needs to be assigned to all trusted roles who have access to “Full HTML”. You may also want to assign an editor for basic “Anonymous” and “Authenticated” users. Untrusted roles should probably not be allowed to add images, headings or other special tags. The included “Commenter” editor configuration is likely appropriate for your “Filtered HTML” needs, but if you add any additional buttons to be used by roles who only have access to “Filtered HTML”, be sure to make corresponding changes to the “Allowed HTML tags” in your “Text formats” configuration:
admin/config/content/formats/filtered_html
As mentioned before, you could also configure the BBCode editor or set up an editor for other special markup languages. Exploring these use cases is outside the scope of this article.

More advanced configuration

You can do a lot more with the BUEditor… this article might be a bit long, but the official documentation is even longer. There are loads of API functions for doing really cool stuff with BUEditor buttons; and don’t overlook all the pages of contributed button code. Before you spend a lot of time trying to figure out how to implement a particular button for your needs, take a look at what’s already tested and available; even if you don’t want the exact functionality offered by a contributed button, it may offer an example you can more easily adapt to achieve your particular needs.

Some of my favorite contributed buttons include the:

• Special Characters button, which provides a nice pop-up panel for just about any “special character” a user might want to insert
• Text Color button, which provides a pop-up selector with color swatches which can be applied to text or backgrounds
• Class Attribute Library; allows easy addition of a particular class to selected HTML
• Smileys Button, which provides reasonable integration with the Smileys module (unfortunately not yet officially available for Drupal 7, though it does look like the port is reasonably complete.)
• Remove Formatting button (perhaps less risky than the one I created since it only strips designated tags, so won’t remove everything inside of IMG tags or between the php tagset used for longer blocks of syntax-highlighted code.)
• BUEditor Imagecache button (similar to the standard insert image button, but also allows selection of a pre-set image style)
• BUEditor Quick Table (okay, HTML tables are worth avoiding, but sometimes data content really is best displayed in a table; this makes it easy)

Good luck and have fun…

We wish you every success configuring your Drupal site for maximum productivity and a user experience to write home about. The BUEditor might not be for everyone or every use case, but its light-weight code-base is amazingly efficient and with the proper configuration it can be better than a WYSIWYG editor for offering a friendly way to add and edit content. If you come up with some interesting things to do with it or have comments about this article, or any of our others, we look forward to hearing from you. Please feel free to leave a comment, below.

Thank you for visiting us on the Cocomore Drupal blog.