1. Chris Laplante Avatar Chris Laplante
  2. Untitled project
  3. dialogWrapper

Wiki

Clone wiki

dialogWrapper / Home

View History

Note: Version 2.1.* of dialogWrapper has been released! With it comes some important API changes that you should be aware of. Most importantly, methods are now namespaced by default. Please see this blog post for details: http://mostthingsweb.com/?p=502

Introduction

Current version: 2.1.1

dialogWrapper is a plugin that aims to make using jQuery UI Dialogs much, much simpler. Currently, you have to go through these steps to use a dialog:

  1. Define the dialog in the HTML at design time
  2. Initialize the dialog ahead of time
  3. Display it when you need it

The main problem with this approach is that it is not always known, at design time, which dialogs will be used, so it is impossible to define all of them ahead of time. This is the main problem that dialogWrapper corrects, through dynamic dialog creation. Instead of going through all the steps above, you can simply do this:

$.dW.createDialog("Title", "This is the message prompt/body", {
    buttons: {
        'Ok' : function(){
            $.dW.hideDialog(this);
        }
    }
});

Much easier. dialogWrapper also adds the following improvements:

  • When stacking dialogs that each create a modal, it is sometimes not desired for the opacities to also stack up, thus dimming the page more and more with each successive dialog. dialogWrapper offers the ability to only keep the overlay on the topmost dialog. This feature can also be applied to standard dialogs.
  • The option to remove the close link ("X") on the title bar for dynamically created dialogs.
  • Removes the need for you to predefine the dialog's hide effect by letting you pass the effect to the $.hideDialog() method.
  • Methods for hiding or destroying the topmost dialog, as well as hiding or destroying every dialog
  • A helper method for getting the topmost dialog
  • Helper methods for dynamically showing alert, confirm, and input dialogs

Demo

Building

If you want to build the files yourself, follow these instructions:

  1. Install Node.js.
  2. Install Grunt by opening a command line and typing: npm -g install grunt
  3. Download the dialogWrapper source by either cloning this repository, or downloading a zip/tar file. See the Downloads tab above.
  4. Open a command line, point it to the root directory of the source (the folder containing grunt.js, and invoke grunt. On Windows, this means typing grunt.cmd. On other platforms, type grunt.
  5. The normal and minified versions will be written to the dist folder.

If any errors occur during the build process (for example, if lint throws a warning/error), please comment on my blog or open a new ticket.

License

This project is under an MIT license.

API Reference

The API reference consists of two parts: The methods, and the options that dialogWrapper extends the existing jQuery UI Dialog options with. The set of options covered in the Options section only applies to $.dW.createDialog(), $.dW.alert(), $.dW.confirm(), and $.dW.input(). Options for are other methods are explicitly stated in the documentation for the methods themselves.

Methods

$.dW.createDialog (body)

Description: Dynamically creates a dialog (without a title or options) and shows it.

Arguments:

  • body: The dialog content, HTML allowed (required) Returns: The dialog object 

$.dW.createDialog (body, options)

Description: Dynamically creates a dialog (without a title) and shows it.

Arguments:

  • body: The dialog content, HTML allowed (required)
  • options: Options used to customize the look and feel of the dialog, from either the documentation or the Options section below (optional) Returns: The dialog object 

$.dW.createDialog (title, body, options)

Description: Dynamically creates a dialog and shows it.

Arguments:

  • title: The dialog title, HTML allowed (required)
  • body: The dialog content, HTML allowed (optional)
  • options: Options used to customize the look and feel of the dialog, from either the documentation or the Options section below (optional) Returns: The dialog object 

$.dW.hideDialog (dialog, options)

Description: Hides (but does not destroy or remove) the given dialog.

Arguments:

  • dialog: An identifier for the dialog to be hidden (required)
  • options: Options that control how the dialog is hidden. Currently, the only option that is supported is hide, which specifies the effect to be used when hiding the dialog (optional) Returns: True or false, depending on success 

$.dW.hideDialogs ()

Description: Hides (but does not destroy or remove) all visible dialogs

Returns: True or false, depending on success; one failure returns false 

$.dW.destroyDialog (dialog, options)

Description: Destroys (or removes) the given dialog.

Arguments:

  • dialog: An identifier for the dialog to be hidden (required)
  • options: Options that control how the dialog is destroyed. Currently, the options supported are: hide, which specifies the effect to be used when hiding the dialog, and remove which, when true, removes (permanently) the dialog instead of destroying it (optional) Returns: True or false, depending on success 

$.dW.destroyDialogs (remove)

Description: Destroys (or removes) all visible dialogs

Arguments:

  • remove: Whether or not to remove instead of destroy all visible dialogs (optional, default is false) Returns: True or false, depending on success; one failure returns false 

$.dW.confirm (prompt, yes, no, options)

Description: Displays a confirm-style dialog, with yes and no buttons that correspond to the supplied yes and no callbacks

Arguments:

  • prompt: The confirm prompt, HTML allowed (required)
  • yes: A function to be executed when the Yes button is clicked; dialog is automatically closed (optional, pass null to omit)
  • no: A function to be executed when the No button is clicked; dialog is automatically closed (optional, pass null to omit)
  • options: Options used to customize the look and feel of the dialog, from either the documentation or the Options section below (optional) Returns: The dialog object 

$.dW.alert (prompt, options, callback)

Description: Displays an alert-style dialog, with an OK button

Arguments:

  • prompt: The alert prompt, HTML allowed (required)
  • options:Options used to customize the look and feel of the dialog, from either the documentation or the Options section below (optional)
  • callback: A function to be called when the OK button is clicked. Returns: The dialog object 

$.dW.input (prompt, options, callback)

Description: Displays an input-style dialog, with a text field and an OK button

Arguments:

  • prompt: The input prompt, HTML allowed (required)
  • options:Options used to customize the look and feel of the dialog, from either the documentation, the Options section below, or the defaultValue property, which specifies the default value for the text field (optional)
  • callback: A function to be called when the OK button is clicked. The value of the text field is passed as an argument (required) Returns: The dialog object 

$.dW.getTopDialog ()

Description: Returns the topmost, visible dialog.

Returns: The topmost, visible dialog (returns the dialog object) 

$.dW.classicMode ()

Description: Restores the "old" functions. For example, you can use $.input instead of $.dW.input.

Properties

$.dW.version

Description: The version of dialogWrapper (a string).

Options

The following options apply only to the options parameter of the $.dW.createDialog(), $.dW.alert(), $.dW.confirm(), and $.dW.input() methods. They are in addition to the native jQuery UI Dialog options. 

hasClose

Description: Whether or not to include the close link (X) at the top-right of the dialog title bar. The default is true. 

id

Description: The id of the dynamic dialog to be created. Use this property to explicitly set the id of the new dialog. The default is the prefix "dWd" with a random number appended to it. The id of a newly created dialog is the return value of either the $.dW.createDialog(), $.dW.alert(), $.dW.confirm(), and $.dW.input() methods.

Examples

Simple dialog

This creates a dialog with just a body; no title and no buttons.

$.dW.createDialog("Just a body");

Simple dialog (with title)

$.dW.createDialog("Title", "Body", {});

Simple dialog (with buttons)

$.dW.createDialog("Title", "Body", {
    buttons: {
        "Ok" : function(){
            $.dW.removeDialog(this);
        },
        "Cancel" : function(){
            $.dW.removeDialog(this);
        }
    }
});

Modal dialog

$.dW.createDialog("Title", "Body", {
    buttons: {
        "Ok" : function(){
            $.dW.removeDialog(this);
        },
        "Cancel" : function(){
            $.dW.removeDialog(this);
        }
    },
    modal: true
});

Input dialog

$.dW.input("This is an input dialog", {
    defaultValue: "This is the default value"
}, function(value){
    $.dW.alert("You typed: " + value);
});

Changelog

Version 2.*

Version 2.1.1

  • Added the grunt build system
  • Some minor fixes to make lint happy

Version 2.1

New Features

  • Callbacks for alert, input, and confirm are called using the context of the dialog, so calls to, for example, destroyDialog(this) will work inside a callback
  • Added a callback argument to alert that is fired when the Ok button is clicked and the dialog has closed
  • Custom dialogWrapper options (hasClose is the only one so far) are now defaulted in $.ui.dialog.prototype.options, instead of a private variable, so users can modify it as they please
  • You can now change the hasClose option at runtime using the usual method (.dialog("option", "hasClose", value)).
  • Added method to recreate classic methods (e.g. $.input instead of $.dW.input())
  • Version is now provided through $.dW.version
  • Exposed 'findDialog': A helper method for resolving an identifier to a dialog

Improvements

  • IMPORTANT! Namespaced all public methods into $.dW namespace

Bugfixes

  • Internal improvements of stacked overlay handling
  • createDialog (and alert, input, and confirm by extensions) now returns the dialog itself instead of its id
  • destroyDialog now waits for the dialogclose event before destroying (and optionally removing the dialog). This is so that hide-animations can fire properly.
  • Fixed a minor implementation flaw in getTopDialog()
  • Removed unneeded usage of $.extend in input
  • Changed $.extend to use deep (recursive) copy in createDialog, input, alert, and confirm
  • confirm now requires a yes and no callback
  • input now requires a callback
  • Arguments for input, confirm, and alert were supposed to be optional but I forgot to default args to {}. This is fixed
  • Fixed all instances where a dialog was referenced by .ui-dialog and not .ui-dialog-content

Minor Changes

  • Removed the smartModals and smartModalsForClassicDialogs options: these are always enabled and cannot be turned off
  • Changed default id prefix from dwd to dWd
  • Internal function getTopElement has been renamed to _getTopDialog
  • _getTopDialog is now only used to find the top dialog
  • Some general cleanup: I made sure to use brackets {} for all blocks

Version 2.0.7

  • Fixed issue #2

Version 2.0.6

  • Fixed issue #1

Version 2.0.5

  • Fixed an issue with stacking multiple modals

Versions 2.0.1-2.0.4

  • Fixed a variety of issues
  • Mostly consisting of my failure to use Subversion properly

Version 2.0

New Features

These features were introduced in version 2.0.

  • You can now use standard dialogs (i.e. created at design-time, directly in the HTML) as well as dynamic dialogs (i.e. created by dialogWrapper) at the same time
  • Automatic management of modals and stacked overlays can now also be used with standard dialogs
  • New $.input() method for dynamically creating input boxes, styled exactly the same as your other dialogs
  • There is now a difference between hiding, destroying, and removing dialogs: see API Changes
  • Ability to control the ID scheme for dynamically created dialogs
  • Added a $.getTopDialog utility function that returns the dialog currently on top (topmost)

API Changes

The API in dialogWrapper 2.0.2 was changed slightly. As such, code that used previous versions of dialogWrapper may require modifications. Full backwards compatibility does not exist in the latest version of dialogWrapper. For a detailed description of the new API, please see API Reference below.

Bugfixes

These bugfixes were introduced in version 2.0.

  • jQuery UI Dialog events now properly fire
  • Because native jQuery UI Dialog options are used to achieve fading dialogs in and out, all cross-browser issues with such options should be resolved
  • The id parameter of $.hideDialog() and $.destroyDialog() is now much more forgiving: it will accept an object (the dialog itself), a string (with/without the # and with/without the prefix), or a number (only applicable when the main id component is a number). Also, as with the last version, passing null will select the dialog currently on top (topmost)

Technical

  • Completely rewritten
  • Updated for jQuery UI version 1.8.12
  • 1 KB smaller (when minified) than version 1.7
  • Less obtrusive: Only modifies the jQuery UI Dialog prototype in 1 place as opposed to 4 in the last version

Version 1.*

Version 1.7

  • Fixed a variable name typo

Version 1.6.1

  • Fixed a typo in the minified version

Version 1.6

  • Fixed overlay overflow issues in IE
  • Fixed overlay fadeIn issue in IE

Version 1.5

  • Initial release

Future development

My plan is to continue to actively develop dialogWrapper. I am considering adding the following features (in no particular order):

  • Ajax support
  • Support for jQuery Mobile
  • Backwards compatibility with older versions of jQuery UI
  • More methods for opening dialogs, moving them to the front, and checking whether they are open (intended to provide a simple way of using the existing native jQuery UI Dialog methods)
  • If you think the above enhancements would be useful, please let me know so I can figure out which ones to accomplish first. Additionally, if you have any suggestions, please leave a comment.

Enjoy.

Updated