The thing with configuration screens is they usually have a little more to do than simply display an image or other static content. In fact, most of the ones I’ve written require some sort of AJAX functionality. Using an iframe is perfect for these scenarios as they operate as a self contained window, complete with any custom JavaScript.

I began using Cody Lindley’s ThickBox and more recently DOMWindow to load my iframes dynamically. Whist both of these plugins are great, I found they lacked the ability to truly style the boxes and extending them to add callbacks and extra features was not possible without editing the core JavaScript. I was after a simple yet expandable solution to dynamically open an iframe in a Lightbox style window.

Boxen

The boxen plugin allows you to bind a click event to any element that will open a Lightbox style iframe.

Example

    $('.boxen').boxen();
    $('#boxen_google').boxen('http://www.google.com/');
    $('#boxen_search').boxen('http://www.google.com/search', {
        urlParams: {
            q: 'More Cowbell'
        }
    });

Documentation

boxen([url or options], [options])

Arguments

url or options (optional) – String, Options

If the first parameter is a string, it is used as the URL for the iframe source. Otherwise, it is treated as the options map.

options (optional) – Options

urlParams: {},
showTitleBar: true,
showCloseButton: true,
title: null,
titleAttribute: 'title',
closeButtonText: null,
width: 600,
height: 500,
url: null,
urlAttribute: 'href',
overlayOpacity: 0.8,
overlayColor: null,
modal: false,
postOpen: function(contentAreaElement) {},
postClose: function() {}

Demo

Boxen Demo

Download

• Boxen-1.4.tar.gz (13k)
• Boxen-1.4.zip (14k)

UPDATE 2009-03-20

Boxen now has the ability to open an empty canvas. Simply cancel out any URL by setting the url or urlAttribute options to null. See the demo page for a nifty Google Maps example.

UPDATE 2009-04-06

Boxen 1.2 is now IE6 compatible. Due to the lack of position: fixed, the experience may be a little jerky / flickery when the window is resized and occasionally the transparent overlay may be a few pixels too long or too short however I think this is a case of “near enough is good enough”.

Unfortunately, I’ve had to alter the Boxen “id” attribute naming convention and remove the leading underscore to get it to work in IE6. If you’ve used any custom CSS rules, you’ll need to edit them accordingly.

Also fixed in this version:

• BIG iFrame implementation for overlaying IE6 form controls
• Safari iFrame ID caching bug
• Opera opacity issue

I’ve only tested this using a STRICT doctype and encourage everyone else to do so too.

UPDATE 2009-10-08

Boxen 1.3 contains the following updates:

• Fixed “frameBorder” case sensitivity (thanks Caleb)
• Added more streamlined way to anonymously open a Boxen window

  $.Boxen.open(null, {
      url:'http://www.google.com/',
      title:'Boxen window title'
  });

• Now released under the MIT license

UPDATE 2009-11-30

Boxen 1.4 contains the following updates

• Added “overlayColor” option
• Stylesheet example now includes a “spinner” loading animation (courtesy of http://www.ajaxload.info/). Provided your iFrame / content specifies a background, the spinner will not be visible once the content loads

After sorting through a few, I decided on this one from Jörn Zaefferer. The only problem was, I wanted to use the wonderfully simple Zend Framework AjaxContext Action Helper to produce JSON data as my auto-complete data source. I like JSON as it’s easy to produce and easy to deal with in disparate systems (such as PHP and JavaScript). Unfortunately, Jörn’s plugin is built to work with a simple, formatted ASCII list delimited by newlines. Fortunately, he also put a lot of work into this plugin, he just hasn’t gotten around to documenting it all yet.

For this post, I’ll assume my AJAX request is for some user data out of LDAP (or a similar data store) and resembles this

{"users":[
    {"uid":"123","displayName":"User 123","mail":"123@example.com"},
    {"uid":"456","displayName":"User 456","mail":"456@example.com"},
    {"uid":"789","displayName":"User 789","mail":"789@example.com"},
]}

The secret to extending the Autocomplete plugin is the ability to overwrite certain core functions, primarily parse. The internal version of this function simply loops over each line of the returned data and “parses” it into an array of objects, each containing the following attributes:

• data – the entire entry
• value – the default display value
• result – the data to populate the input element on selection

You can overwrite this by passing your own parse function as part of the options object to autocomplete. Mine also includes a custom formatItem function for displaying each entry.

var acOptions = {
    minChars: 3,
    max: 100,
    dataType: 'json', // this parameter is currently unused
    extraParams: {
        format: 'json' // pass the required context to the Zend Controller
    },
    parse: function(data) {
        var parsed = [];
        data = data.users;
 
        for (var i = 0; i < data.length; i++) {
            parsed[parsed.length] = {
                data: data[i],
                value: data[i].displayName,
                result: data[i].displayName
            };
        }
 
        return parsed;
    },
    formatItem: function(item) {
        return item.displayName + ' (' + item.mail + ')';
    }
};

The autocomplete plugin will now accept and parse JSON data.

Another thing I wanted to do with this page was to show one value but use another. In this case, I only want to display the user names and email addresses and use the UID without displaying it or putting it into the form field. This is where having each item available as a JSON object comes in very handy.

For this trick, I’ll add a hidden input field and place the UID into that when an item is selected. Here’s my form field

<input type="text" id="user_id" name="user_id">

and here’s the JavaScript

// autocomplete options as above
 
jQuery(document).ready(function($) {
    $('#user_id')
        .autocomplete('/path/to/ajax/data/source', acOptions)
        .attr('name', 'display_name')
        .after('<input type="hidden" name="user_id" id="ac_result">')
        .result(function(e, data) {
            $('#ac_result').val(data.uid);
        });
});

The reason I changed the name attribute of the original input and gave it to the new hidden one is so I can still submit the form normally and work with the submitted “user_id” value.

The Autocomplete result function receives the selected item’s data property when an item is selected. With the above configuration, this is the actual JSON object