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

Utility methods and Class wrappers

### Table of contents

NAME
SYNOPSIS
DEPENDENCIES
DESCRIPTION
Windows.Ext
Methods
Windows.Ext.relateWindows(parentWindowId, childWindowId)
Windows.Ext.handFocus(windowId)
Windows.Ext.hideWindow(windowId)
Windows.Ext.destroyWindow(windowId)
Window.Ext Options
Window.Ext Classes
Window.Ext.HTMLWindow
Javascript
Window.Ext.AJAXWindow
Javascript
Window.Ext.IFRAMEWindow
Javascript
Dialog.Ext Utilities
Dialog.Ext.Error(error_message)
Javascript
Dialog.Ext.Alert(alert_message, callback)
Javascript
Dialog.Ext.Progress(message, callback)
Javascript
Dialog.Ext.Confirm(confirmation_message, ok_callback, cancel_callback)
Javascript

## 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
        }
      );