Using a WYSIWYG Dojo Editor in a Play! Form

This post contains declarative code for integrating the Editor Dijit from the Dojo Toolkit.  The code declares an Editor Dijit on a <div> element, submits the content via a hidden <textarea>. and mediates the two elements with an onChange() handler.

The Editor Dijit from the Dojo Toolkit is a powerful WYSIWYG text widget.  Editor can control formatting as well as advanced functions like redo, full screen view, and pretty printing.  This post describes a scenario where Editor is used for basic style formatting.  It assumes some Dojo knowledge of including the libraries and stylesheets in an HTML page.

A Form using ValidationTextBox, Editor, and Button Dijits

The Play! Framework

The Play! Framework is a dynamic MVC implementation.  Play! processes forms using a request/response model (versus event-driven).  Play! has a great syntax for binding forms to controller logic.  For example, the following form -- supplemented with Dijits from the Dojo toolkit --- will invoke the controller method createTextualProc().

Play! Form with Dijits

This form picks up 'tutorial_id' from a calling controller method.  Several fields are defined (like 'proc_title_tx') that will be submitted along with tutorial_id.  The specific method invocation on createTextualProc() will be the following with all form variables bound to Java method arguments.


public static void createTextualProc(Long tutorial_id, String proc_title_tx, String proc_desc_tx, String save_b, String cont_b)


For more on Play! Framework controllers and the interaction between controllers and the data model, see the documentation.

With Dijits

A Javascript toolkit like Dojo enhances the Play! UI through client-side validation, WYSIWYG editing, and more pleasing controls through fading and highlighting. "Dijits" are Dojo widgets that enhance HTML versions  (like Button) or construct more complex controls (like Editor, Calendar, or ColorPalette). For more information on the Dojo toolkit and Dijits, visit the documentation page.

There are two techniques for using Dijits in view code: declarative and programmatic.  This post's examples are declarative which means that the Dijit definitions are mixed with the HTML.  Note that there is a new declarative HTML 5 syntax being adopted which doesn't hijack the standard (dojoType isn't a valid XHTML <input> attribute).  The programmatic technique puts all definitions in Javascript using constructors and setters.

Editor Dijit

Simple Dijits like Button and ValidationTextBox are annotation of existing HTML components.  As a result, they're submitted along with a form.  To use Editor in a standard HTML form, you need to add extra markup to create a hidden <textarea> element that will be responsible for submitting the Editor data.

In the screenshot "Play! Form with Dijits", the Editor Dijit is integrated with an HTML form in three parts.  The first part is the Dijit definition which is a <div> annotation with dojoType="dijit.Editor".  The second part is a hidden <textarea> element containing an id/name pair that is to be the submitted variable name.  The last part is a block of Javascript that will link the Editor with the <textarea> when the Editor is changed, making it available for form submission.

Notes

I'm relying on the Play! Framework's #{field} tag to define the ids and names of the Editor Dijit, <textarea>, and a label (&{field.name}).  I established a convention that the Dijit will use the same name as the <textarea> plus a "_ed" suffix.  Although you can use hardcoded ids and names, the block will be more portable if the form variable name (proc_desc_tx) can be changed in a single place.  A custom tag can also help with reuse.

Filling in Values

The "Play! Form with Dijits" code displays a blank form.  This is a snippet of a form that will start with a value.  Note the ${field.value} tag.  Also, this is referring to a different form variable which uses a dot notation to bind to an object's fields.

Filled-in Value

Troubleshooting

These are a few troubleshooting tips to check if don't see the editor control or it comes up malformed.

1. Editor doesn't display.  Check the height attribute.
2. Content not submitted with form.  Check for a name mismatch on the <textarea> or in the coordinating Javascript.  
3. Empty content.  Make sure that your event handler is being called.  If you can't get the declarative <script> to fire, comment it out and try calling a Javascript function from the Editor itself by using something like onClick="myfunction()" on the Editor <div>
4. Editor is misshapen or not rendering correctly.  There is a problem with the included styles.  Make sure that the <body> element has a class with a theme like "claro" and that that class' stylesheet is included ("dijit/themes/claro/claro.css").
5. Opera.  I've had some trouble getting the onChange to consistently fire on Opera.  Check your page in another browser.  If there's an Opera problem, create a submit handler that will transfer the Dijit value to the <textarea>. 

An Opera Workaround

#{form @saveTextualProc(), onsubmit: 'updateDesc()'}