Ultima Dialog

Ultima Dialog is a feature rich (modal) dialog component written in JavaScript, using only jQuery core functionalities. The dialog is able to hold complex DOM content, supports AJAX and solves several problems many other dialogs do not even consider. Some of the features are:

  • supports all common content types: plain text, DOM elements (HTML), images, videos, audio, ajax calls, iFrames
  • supports form submission within the dialog and loads the result in the same dialog
  • supports multiple dialogs at once as well as stacking multiple dialogs
  • considers window size (viewport) and prevents overflow und truncation of the dialog''s content
  • offers smooth transitions (adjustable) on resize and reposition of the dialog
  • offers animations and filter effects
  • offers various callbacks and interrupts
  • offers easy-to-use shorthand options and methods
  • does not require you to add HTML, CSS or images
  • does not require additional JavaScript libraries other than jQuery 1.4+
  • is browser backwards compatible down to Internet Explorer 8

// Documentation

    // Include

    You can place the UltimaDialog script include basically wherever you want, just make sure that jQuery is loaded before. jQuery is required and must be at least version 1.4 to work with Ultima Dialog. Remember to pick jQuery 1.x if you need support for Internet Explorer ≤ 8, otherwise pick 2.x or 3.x.

    1. body
    2. head
    1. <html>
          <head>

              ...

              <script src="jquery.js"></script>

          </head>
          <body>

              ...

              <script src="jquery.ultima.dialog.js"></script>

          </body>
      </html>

    // Initialization

    You can create an instance of the UltimaDialog class by using the native new operator (explicit) or the available jQuery wrapper methods (implicit).

    1. implicit
    2. explicit
    1. var dialog = $.UltimaDialog.show('Hello World !!');

      - OR -

      $('<span>Hello World !!</span>').UltimaDialog();

    // Constructors

    Note: You can also use the $ alias instead of the fully qualified jQuery.

    • new UltimaDialog ( options ) : UltimaDialog
      native object constructor, manual method invocation required
    • jQuery.UltimaDialog ( options ) : jQuery
      e.g. $('#foo').UltimaDialog();
      clones the HTML content of the preceding jQuery object and pass it to a newly created instance of UltimaDialog, invokes the show() method
    • jQuery.UltimaDialog.show ( content, options ) : UltimaDialog
      creates an instance of UltimaDialog and invokes the show() method
    • jQuery.UltimaDialog.image ( image, attributes, options ) : UltimaDialog
      creates an instance of UltimaDialog and invokes the image() method
    • jQuery.UltimaDialog.video ( video[], attributes, options ) : UltimaDialog
      creates an instance of UltimaDialog and invokes the video() method
    • jQuery.UltimaDialog.audio ( audio[], attributes, options ) : UltimaDialog
      creates an instance of UltimaDialog and invokes the audio() method
    • jQuery.UltimaDialog.get ( url, data, callback, options ) : UltimaDialog
      ajax: creates an instance of UltimaDialog and invokes the get() method (HTTP GET)
    • jQuery.UltimaDialog.post ( url, data, callback, options ) : UltimaDialog
      ajax: creates an instance of UltimaDialog and invokes the post() method (HTTP POST)
    • jQuery.UltimaDialog.put ( url, data, callback, options ) : UltimaDialog
      ajax: creates an instance of UltimaDialog and invokes the put() method (HTTP PUT)
    • jQuery.UltimaDialog.delete ( url, data, callback, options ) : UltimaDialog
      ajax: creates an instance of UltimaDialog and invokes the delete() method (HTTP DELETE)
    • jQuery.UltimaDialog.iframe ( url, attributes, options ) : UltimaDialog
      creates an instance of UltimaDialog and invokes the iframe() method

    // Methods

    Note: The highlighted UltimaDialog refers to an instance of UltimaDialog while the non-highlighted refers to the static namespace.

    • UltimaDialog.show ( content, options ) : boolean
      shows the specified content
    • UltimaDialog.image ( image, attributes ) : boolean
      shows the specified image
    • UltimaDialog.video ( video[], attributes ) : boolean
      shows the specified video
    • UltimaDialog.audio ( audio[], attributes ) : boolean
      shows the specified audio
    • UltimaDialog.get ( url, data, settings, options ) : boolean
      wrapper method for jQuery.ajax( { method: 'GET' } )
    • UltimaDialog.post ( url, data, settings, options ) : boolean
      wrapper method for jQuery.ajax( { method: 'POST' } )
    • UltimaDialog.put ( url, data, settings, options ) : boolean
      wrapper method for jQuery.ajax( { method: 'PUT' } )
    • UltimaDialog.delete ( url, data, settings, options ) : boolean
      wrapper method for jQuery.ajax( { method: 'DELETE' } )
    • UltimaDialog.iframe ( url, attributes ) : boolean
      shows the specified website in an iFrame
    • UltimaDialog.close ( callback ) : boolean
      closes the dialog
    • UltimaDialog.close ( index, animate = true ) : boolean
      closes the dialog at the specified index, considers the most recent dialog if index is undefined
    • UltimaDialog.closeAll ( animate = true, deferProgression = false ) : boolean
      closes all dialogs
    • UltimaDialog.get ( index ) : UltimaDialog
      returns the dialog at the specified index, considers the most recent dialog if index is undefined
    • UltimaDialog.isOpened ( index ) : boolean
      returns if the dialog at the specified index is opened, considers the most recent dialog if index is undefined
    • UltimaDialog.relocate ( index ) : boolean
      relocates (resizes and repositions) the dialog at the specified index, considers the most recent dialog if index is undefined,
      call this method if you change the dialog's content programmatically
    • UltimaDialog.setOptions ( index, options, overwrite = false ) : boolean
      update the dialog options at the specified index, considers the most recent dialog if index is undefined,
      options can be merged (default) or completely overwritten,
      be aware of the fact that only a few specific options will be considered for an already shown dialog

    // Options

    Note: The options object is deeply structured, consisting of several sub-objects (nested objects). There are two notations available:

    1. verbose (native)
    2. shorthand (resolved)
    3. changing defaults
    1. var options = {

          behavior: {

              closeOnCurtain:      false

          },

          css: {

              curtain: {

                  backgroundColor: '#FFFFFF'

              },

              window: {

                  backgroundColor: '#9A64FF',
                  color:           '#FFFFFF',

                  border:          '2px solid #000000'

              }

          }

      }
      ;
    animations
    curtain
    show
    effect'fadeIn'effect used to show the curtain
    duration400duration of the above effect
    hide
    effectundefinedeffect used to hide the curtain
    undefined: inherit value from show
    durationundefinedduration of the above effect
    undefined: inherit value from show
    deferProgressionfalsewait for curtain to be fully shown before progressing to the dialog window
    window
    show
    effect'fadeIn'effect used to show the dialog window
    duration400duration of the above effect
    hide
    effectundefinedeffect used to hide the dialog window
    undefined: inherit value from show
    durationundefinedduration of the above effect
    undefined: inherit value from show
    deferProgressionfalsewait for window to be fully hidden before progressing to the curtain
    reposition
    duration100animation duration for repositioning the dialog
    resize
    duration200animation duration for resizing the dialog content
    rate200polling rate to watch for resize of the viewport
    behavior
    ajax
    cachefalsecache ajax requests
    closeOnCurtaintrueclick on the curtain will trigger closing of the dialog
    closeOnEscapetruepressing the ESC key will trigger closing of the dialog
    this value will override the behavior of already opened dialogs
    (overrides global handler)
    closeOnWindowtrueprepend an element that triggers closing of the dialog
    styling required, see -> css.window.close
    disableScrolling'auto'disable scroll on body
    auto: disable on overflow only (avoids multiple scrollbars)
    preventOverflowtrueautomatically limit the size of the dialog content to prevent overflow
    trackSubmittrueautomatically assign submit handlers to every form element found in the dialog content
    translateMediatruetranslate plain content automatically to the corresponding media
    (affects images, video and audio only)
    zIndexInctrueincrement the zIndex for every parallel existing dialog
    css
    loading
    className''class added to the loading notification (affects ajax and images only)
    contentundefinedcontent to be placed within the loading notification
    x'50%'horizontal position of the loading notification, either in px or in %
    y'50%'vertical position of the loading notification, either in px or in %
    < css property >any CSS property, will be set as inline style
    curtain
    applyFilterundefinedCSS3 filter applied to the curtain, e.g. blur(4px), grayscale(100%)
    className''class added to the curtain element
    isVisibletruedraw curtain with a (non-transparent) color
    zIndex9003
    < css property >any CSS property, will be set as inline style
    window
    className''class added to the window element
    close
    className''class added to the close control element
    < css property >any CSS property, will be set as inline style
    hardMarginX0margin applied to the width of the viewport
    hardMarginY0margin applied to the height of the viewport
    x'50%'horizontal position of the window, either in px or in %
    y'50%'vertical position of the window, either in px or in %
    zIndex9004
    < css property >any CSS property, will be set as inline style
    callbacks
    onOpeningundefinedbefore opening
    (UltimaDialog) : return false to interrupt
    onCurtainOpenedundefinedafter curtain is fully shown
    (UltimaDialog)
    onWindowOpenedundefinedafter window is fully shown
    (UltimaDialog)
    onContentReadyundefinedafter content is known and ready to be placed
    (UltimaDialog, content) : return false to interrupt
    onContentVisibleundefinedafter content is fully shown
    (UltimaDialog)
    onAsyncSuccessundefinedafter asynchronous request returned an expected result
    (UltimaDialog, response)
    onAsyncErrorundefinedafter asynchronous request returned an unexpected result
    (UltimaDialog, request)
    onSubmitundefinedbefore submit within dialog is sent
    (UltimaDialog, data) : return false to interrupt
    onClosingundefinedbefore closing
    (UltimaDialog) : return false to interrupt
    onCurtainClosedundefinedafter curtain is fully hidden and removed
    (UltimaDialog)
    onWindowClosedundefinedafter window is fully hidden and removed
    (UltimaDialog)

    // Examples

    You can test UltimaDialog in your browser console as well.

    1. show text message
    2. show DOM element
    3. show modal dialog
    4. show styled dialog
    1. GET content via ajax
    2. POST content via ajax
    3. show iFrame
    1. show small image
    2. show large image
    3. show video player
    4. show audio player
    5. show YouTube video
    1. multiple / stacking dialogs
    2. oversized content in dialog
    3. animations in detail
    4. alert on each callback

    // License

    MIT, Copyright (c) 2014-2018 Alexander Kwaschny, kwaschny.net

    // Download