Window (http://prototype-window.xilinus.com/) Extension Class

NAME

Window (http://prototype-window.xilinus.com/) Extension Class - Utility methods and Class wrappers

SYNOPSIS

Composed of three subclasses

Extension to Windows Class

Extension to Window Class

Extension to Dialog Class

DEPENDENCIES

This class depends on

DESCRIPTION

This class was developped to make the instantiation and manipulation of Window objects easy, uniform and DMWeb ready.

This class introduced the following new concepts/bug fixes to the original Window class.

  • windows parent/child relationship

    a logical way for window recycling

  • focus aware

    for a consistant keyboard navigation

  • scroll offset aware

    window location can be set in an absolute way. default window location (top/left) to center.

  • clearOnClose option

    for memory reasons, closed windows will remain in the DOM but their content will be erased.

  • fluid height

    if the height of the window is not set, the window will resize to fit its content.

  • window fullscreen

    an easy way to set the dimensions of the window to fullscreen

  • JS Stash

    windows that have their content bound to an XHR request, will have access to an in-memory hash used to store js variables.

It defines 3 classes of windows:

  • Window.Ext.HTMLWindow

    Window that has its content ready as an html(+javascript).

  • Window.Ext.AJAXWindow

    Window that would retrieve its content via XHR request.

  • Window.Ext.IFRAMEWindow

    Window that has an iframe embdedded in its content.

And 4 types of dialogs:

  • Dialog.Ext.Error

    A dialog displaying an error message

  • Dialog.Ext.Alert

    A dialog with an alert message

  • Dialog.Ext.Confirm

    A dialog with a confirmation message

  • Dialog.Ext.Progress

    A dialog with a progress indicator and an informational message

It also provides utility methods to control the application focus mainly when a window/dialog opens and closes.

Windows.Ext

Contains utility methods for showing/hiding, opening/closing ... window instances.

Methods

Windows.Ext.relateWindows(parentWindowId, childWindowId)

(Mostly used internally)

Establishes a parent/child relationship between 2 windows. This relationship will enforce the following behaviour:

    parent closed    -> close all children
    parent destroyed -> destroy all children
  • parentWindowId (string)

    Id of the window to act as the parent

  • childWindowId (string)

    Id of the window to act as the child

Windows.Ext.handFocus(windowId)

(Mostly used internally)

Hands the focus to a Window instance by 'activating' the window's focus_target. If not defined, the window's first editable input will be focused.

  • windowId (string)

    Id of the window to give focus to.

Windows.Ext.hideWindow(windowId)

(Mostly used internally)

Hides a Window instance while keeping it in the DOM.

  • windowId (string)

    Id of the window to hide.

Windows.Ext.destroyWindow(windowId)

(Mostly used internally)

Destroys a Window instance and removes it from the DOM.

  • windowId (string)

    Id of the window to destroy.

Window.Ext Options

Details of all Window.Ext options (shared by all Window.Ext instances).

All window instances in the Window.Ext namespace share an identical set of options that is an extension to the original set defined in Window namespace.

For sake of brevity, only the extended options and the options that have been defaulted will be documented here.

For the full list of Window Options, please refer to http://prototype-window.xilinus.com/.

  • className (string)

    Window className to define its look and feel.

    optional - defaulted to 'mac_os_x'

  • maximizable (boolean)

    optional - defaulted to false.

  • modal (boolean)

    flag to set whether the window opens as a modal window or not.

    optional - defaulted to false.

  • fullscreen (boolean)

    if set to true, the window dimension/location will be overloaded.

    optional - defaulted to false.

  • resizable (boolean)

    optional - defaulted to ! fullscreen

  • width (numeric)

    required - in case of fullscreen

  • height (numeric)

    optional - defaulted to height of the window content

  • top (numeric)

    optional - defaulted to middle

  • left (numeric)

    optional - defaulted to center

  • destroyOnClose (boolean)

    optional - defaulted to false

  • clearOnClose (boolean)

    flag whether to clear the content of a window before it closes.

    optional - defaulted to true

  • owner (string)

    Id of the window to as a parent.

    optional

  • focus_targets (string|array)

    string id or array of string ids of elements that the window will hand focus to when it opens.

    optional

  • onSuccess (function)

    callback to executes when the window succeeds to open and to set its content

    optional - defaulted to empty function

  • onTabOut (function)

    callback to execute when the user tabs out the window.

    optional - defaulted to window.focusWindow()

Window.Ext Classes

Window.Ext.HTMLWindow

Javascript

HTML Window instantiation

 /**
  * finds/creates a window object with given id and options.
  * opens/maximizes/bringsToFront the window object.
  * sets its content to the html provided.
  * evaluates the javascript (if any) that is included in the html content.
  * calls the onSuccess function.
  */
  new Window.Ext.HTMLWindow('win_id', 'win_html_content', {
    title          : 'CHANGE_ME',
    owner          : 'owner_window_id', 
    focus_targets  : 'CHANGE_ME',
  
    modal          : false, 
    fullscreen     : false, 
    
    destroyOnClose : false,
    clearOnClose   : true,
    
    width             : 0,
    height            : 0,
    top               : null,
    left              : null,
  
    // window events
    onSuccess : function(win) {
        // window openned successfully
    },
  
    onClose : function(win) {
        // window closes
    },
  
    onTabOut : function(win) {
        // user tabs out of the last input in window
    }
  });

Window.Ext.AJAXWindow

Javascript

AJAX Window instantiation

 /**
  * finds/creates a window object with given id and options.
  * opens/maximizes/bringsToFront the window object.
  * sets its content to the response of XHR.
  * evaluates javascript (if any) embedded in the XHR response.
  * calls the onSuccess function
  */
  new Window.Ext.AJAXWindow('win_id', 'win_url_ajax', {
    title          : 'CHANGE_ME',
    owner          : 'owner_window_id', 
    focus_targets  : 'CHANGE_ME',
  
    modal          : false, 
    fullscreen     : false, 
    
    destroyOnClose : false,
    clearOnClose   : true,
    
    width             : 0,
    height            : 0,
    top               : null,
    left              : null,
  
    // window events
    onSuccess : function(win) {
        // window openned successfully
    },
  
    onFailure : function(win) {
        // window failed to open (due to failure in AJAXRequest)
    },
  
    onClose : function(win) {
        // window closes
    },
   
    onTabOut : function(win) {
        // user tabs out of the last input in window
    }
  });

Window.Ext.IFRAMEWindow

Javascript

IFRAME Window instantiation

 /**
  * finds/creates a window object with given id and options.
  * opens/maximizes/bringsToFront the window object.
  * sets its IFRAME src to the url provided.
  * calls the onSuccess function.
  */
  new Window.Ext.IFRAMEWindow('win_id', 'win_iframe_url', {
    title          : 'CHANGE_ME',
    owner          : 'owner_window_id', 
    focus_targets  : 'CHANGE_ME',
  
    modal          : false, 
    fullscreen     : false, 
    
    destroyOnClose : false,
    clearOnClose   : true,
    
    width             : 0,
    height            : 0,
    top               : null,
    left              : null,
  
    onClose : function(win) {
        // window closes
    },
  
    onTabOut : function(win) {
        // user tabs out of the last input in window
    }
  });

Dialog.Ext Utilities

Namespace that contains utilities to open different kind of dialogs.

Dialog.Ext.Error(error_message)

Displays the error_message in an 'error-styled' dialog.

Javascript

  Dialog.Ext.Error("error message");

Dialog.Ext.Alert(alert_message, callback)

Displays the alert_message is an 'warning-styled' dialog. Callback will be executed with the closure of the dialog.

Javascript

  Dialog.Ext.Alert("alert_message", function() {
    // alert window has been closed
  });

Dialog.Ext.Progress(message, callback)

Opens a dialog with a progress indicator and message. Callback will be executed after a 1sec delay.

Javascript

  Dialog.Ext.Progress("progress_message", function() {
    // progress window displayed for 1sec
    // do this next
  });
  // close progress window
  Dialog.Ext.endProgress();

Dialog.Ext.Confirm(confirmation_message, ok_callback, cancel_callback)

Opens a dialog with confirmation message and an OK and Cancel buttons with designated callbacks.

Javascript

  Dialog.Ext.Confirm("conrfirmation_message", 
    function() {
        // user clicked ok
    }, 
    function() {
        // user clicked cancel
    }
  );