Java The Hutt

I spent some time this past week looking at the various solutions out there for creating a modal dialog and while I was nearly able to make each of them work there were varying degrees of ugliness required.

First off my requirements:

I need to have a page containing a form that also contains a few different lists of user created items. Now I know that some will think that this might be a usability nightmare but in the flow of the user it makes sense and works. So imagine if you will:

< form>
   (text fields, area)
   list1
     < a href>Add new thing to list1< /a>
   list2
     < a href>Add new thing to list2< /a>
   list3
     < a href>Add new thing to list3< /a>
   (text fields)
   submit
< /form>

Now there are some problems with the above requirement. Namely how do I get items into the list without taking the user to another page or doing a full page refresh? I can't create inline popup divs for each list to allow users to add new entries to each list because that requires a form tag and you can't have a form that lives inside of a form.

< form>
   (text fields, area)
   list1
     < a href>Add new thing to list1
       < div id='list1_dialog' style='display: none;'>
         < ajax remote form id='dialog_form'>
           fields...
           submit button
         < /form>
       < /div>
	...
< /form>

That leaves the options of having a div that lives outside of the form and is shown to the user for adding/editing items in the list.

Believe it or not accomplishing that is not an easy feat mainly because I want a modal dialog that will allow for adding/editing these lists without doing a page refresh. Luckily I was able to figure out a solution and while I'm sure all of the following modal dialog implementations will work I only got my solution working with just one, no doubt due to my own javascript deficiencies.

The 3 modal dialog contenders were:

1. Submodal
2. Prototype window class
3. Lighbox gone wild

All of these implementations are just fine and I was able to get a modal dialog working with each of them in fairly short order.

That said, the implementation that I ended up using was lightbox gone wild.
(If you'd like to play along at home I'd suggest going to download LGW and follow along with the posting as it will make things clearer. Just put lightbox.js and lightbox.css in your /javascripts and /stylesheets directory of your rails app, refer to them in your .rhtml page where you'd like to pop the dialog from and you'll be set.)

LGW uses prototype in its implementation just like the prototype window class implementation, but it was considerably cleaner, smaller, and easier to understand. The whole implementation itself is just over 200 lines of javascript code and one stylesheet.

In fact if you don't need anything special you don't even need to write a lick of code to get the thing working.
The following is the minimum required HTML to get a modal dialog working with LGW.

     < link rel="stylesheet" href="css/lightbox.css" type="text/css" />
     < script type="text/javascript" src="scripts/lightbox.js">< /script>
     < a href="text.html" class="lbOn">About Lightbox< /a>

This code creates a link to text.html. When the link is clicked lightbox will create a modal dialog that contains the contents of text.html

Inside of text.html you create a link to close the dialog...

     < a href="#" class="lbAction" rel="deactivate">close< /a>

That's it!

Under the covers there's some cool prototype javascript hacks going on. Namely there are event listeners being setup for all of the elements that are tagged with 'lbAction' and 'lbOn'.

For items tagged with 'lbOn', when they are clicked a modal dialog is created and shown to the user.

For items tagged with 'lbAction' an event listener is created for click events on those items. The callback that is associated with the click is specified by the 'rel' attribute on the element. So in our example above the close link will have an eventlistener created on it that calls back to 'deactivate'.

Seems simple enough and elegant so I should be all set right? Unfortunately no. Now I may very well be missing something but I couldn't get things to work properly, in IE of course, without some trickery that I'll go over.

First my link in 'page.rhtml':

    < %=link_to 'Add contact', {:action => 'add_contact_dialog'}, :class => 'lbOn'%>

That link triggers my dialog. In my dialog screen (dialog.rhtml) I have:

    < %=form_remote_tag :html => {:id => 'add_contact_form', :name => 'add_contact_form'}, :url => {:action => 'add_contact'}%>
    < %=submit_tag button%>< a href="#" class="lbAction" rel="deactivate">cancel< /a>
    < %=end_form_tag%>

Submitting this form to 'add_contact' renders my RJS template (add_contact.rjs):

    page.insert_html :bottom, 'ContactList', :partial => 'list_entry', :object => @contact, :locals => {:hide => true}
    page.visual_effect :blind_down, @html_id
    page.call 'add_lightbox', 'edit'+@html_id

What this template does is

1. take the contact I created, create a list element for it with "edit" and "delete" links. The element is not shown to start because we...
2. create a visual effect to make the element appear that indicates to the user that a new item was added to the list.
3. create a lightbox listener for the "edit" link I created so clicking the link pops the dialog and loads this contact's information for editing.
   

The page.call is calling a javascript function that I created (add_lightbox) and added to lightbox.js, that takes the given DOM id and creates a listener in addition to some other things...

    function add_lightbox(id) {		
      dismiss();
      value = new lightbox($(id));
    }

    function dismiss() {
      lightbox.prototype.deactivate();
      if(browser == 'Internet Explorer') {
        // this is here because lightbox doesn't scroll IE after dismissing after we post forms
        window.scrollTo(0, lightbox.prototype.getYPos());
      }		
    }

As you can see there's some extra stuff going on besides just adding a new lightbox to the element that was passed in. This is the critical point in the implementation where I could only get things working by doing things in this particular order.

There are three important points here:

1. deactivate() must be called from the RJS template (In this instance it is called by dismiss()). It will *NOT* work in IE6 if you try to use a callback with the remote_form_tag, eg:
   

   
   < %=form_remote_tag :html => {:id => 'add_ref_form', :name => 'add_ref_form'}, :url => url, :complete => 'lightbox.prototype.deactivate();'%>
   

   
   Why? I have no idea. I tried other options as well, :loaded, :loading, nothing worked. Of course it works fine with Firefox and Safari. I didn't check IE7 because quite frankly it doesn't matter yet. I need IE6 to work.
2. You must scroll IE after dismissing the dialog.
3. You can only create the lightbox for the newly inserted item after the request is complete because the unique identifier for the edit link isn't available until after it's created. To be fair you could come up with another convention but why? It makes sense to use the ID of the thing you're editing.
   

IE and scrolling:
If you read the tutorial on the LGW page you'll see that they talk about the problem with IE not scrolling back to where it was and that they have code that fixes it. Unfortunately I couldn't get it to work whenever I performed an AJAX form submission. What I ended up doing was creating a class level variable in the lightbox implementation that I use to store the Y-axis position of the scrollbar (I don't care about the X-axis position because my page will never scroll horizontally). I doubt this is the optimal way to accomplish this but hey, it works.

Anyway, the modification of the lightbox.js code is as follows...
Add the function definition 'getYPos' to the prototype object in the lightbox.prototype declaration (hint: put this after the last function in the prototype declaration and put a ','
after the last function definition before pasting in the following code.)

    getYPos: function() {
      return lightbox.yPos;
    }

Then modify the getScroll function as follows:

	getScroll: function(){
	  if (self.pageYOffset) {
		this.yPos = self.pageYOffset;
	  } else if (document.documentElement && document.documentElement.scrollTop){
		this.yPos = document.documentElement.scrollTop; 
	  } else if (document.body) {
		this.yPos = document.body.scrollTop;
	  }
	  lightbox.yPos = this.yPos; <-- set the class level property
	},

This modification sets the class variable yPos on lightbox whenever the dialog is activated and adds an accessor method to get the value.

So going back to the flow of the add_lightbox called from our RJS template we..

1. dimiss the dialog
2. scroll the window to the previous position if IE
   
3. create a new lightbox listener for the newly added DOM element
   

That's it! (heh, not quite as simple as the first example but still not bad now that I've already suffered through the pain of figuring it all out)

The code to edit is very similar except that we don't add the lightbox listener we simply call our dismiss() function after making the edit and HTML update in our RJS template (edit_contact.rjs) as follow:

    page.replace_html @html_id, @contact.to_s
    page.call 'dismiss'
    page.visual_effect :highlight, @html_id, :duration => 3

I hope this is clear to folks. I was thinking of either coming up with a patch, plugin, or submit this to the folks over at LGW and see if they can improve upon it. But for people that need a modal dialog that needs to contain a form and that will dismiss when you click "OK" as well as submit the form, this solution is pretty easy and will suit your needs.

Enjoy!

P.S. - If you liked this post how about a Digg?