MDIware Tutorial

MDIware is a javascript library which provides a Multiple Document Interface (MDI) for browser based programs.

It was created for converting desktop applications to the web with minimal User Interface changes, for an easy transfer of the user's experience.

SIMPLICITY is the key in MDIware design.

Our first sample program will get you started.

Click here to run the Simplest Example of a MDIware application.

The code of the Simplest Example, parent and child forms follows. MDIware specific code is in blue.

CODE OF PARENT FORM 'Parent.htm'

<html>
<head >
<title>Simplest Example</title>


<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js" type="text/javascript" ></script>

<script src="https://MDIware.com/libs/MDIware/MDIware.min.js" type="text/javascript" ></script>
<link href="https://MDIware.com/libs/MDIware/MDIware.css" rel="stylesheet" type="text/css" />

</head>

<body style="background-color:silver;">

<div id='mainDiv' style="background-color:silver;" >

<script type="text/javascript">

// global instance named 'mdi' must exist
var mdi;

$(document).ready(pageInit);

function pageInit()
{

// when jquery is ready init global instance of mdi
mdi = new MDIware('http://MDIware.com/libs/MDIware/');

mdi.topMargin = 35;

// Add two form definitions to be used for child windows.
// The 'url' proprty identifies the web resource to be
// displayed when the form is opened in a window.
// MDI forms have many optional properties to control their
// window's appearance and behavior.
mdi.addForm({"name":"ChildA", "url":"http://MDIware.com/childa.htm", "title":"Child A",
             "width":400, "height":420,
             "resizable":true, "minimizable":true });

mdi.addForm({"name":"ChildB", "url":"http://MDIware.com/childb.htm", "title":"Child B",
             "width":400, "height":420,
             "resizable":true, "minimizable":true});

// Then open two forms in child windows.
        mdi.form('ChildA').show();
        mdi.form('ChildB').show();


}

</script>


<input type='button' value='Open another ChildA' onclick="mdi.form('ChildA').show();" />
<input type='button' value='Open another ChildB' onclick="mdi.form('ChildB').show();" />
<p />
This is a simple MDIware example consisting of 3 web pages:
a parent page (parent.htm) within which we open 2 child windows (ChildA.htm) and (ChildB.htm).
<p />
It demonstrates the simplest use of MDIware windows.
<p />

</div>
</body>

</html>

CODE OF CHILD FORM 'ChildA.htm'

<html>
<head >
<body style="background-color:#ffffe0">
<div>
This is ChildA.htm
<p />

A simple HTML form.
</div>
</body>
</html>

MDI commands used so far

mdi.addForm(formObject)
The addForm command adds a form object to MDI's internal collection of forms. Each MDI form may be accessed by the name: given in the form object definition.

The addForm command has no return value.

mdi.form(formName).show()
The MDI form(formName).show() command creates a visible window using the parameters passed in the previously added form.

The form(formName).show() command returns a system generated window name that identifies the window created. A form can be used multiple times to create multiple windows but each window will have a unique name for future access and manipulation.

Overview - MDIware.js in a Nutshell

MDIware manages an array of forms and an array of open windows.

A MDIware form defines the properties and behaviors of a window. A single form can be opened multiple times to create multiple open windows.

A form is added to the array of forms with the mdi.addForm(formObject) command. At a minimum, a formObject contains the form name, url, and dimensions.

An example of a formObject is {"name":"form1", "url":"child1.htm", "width":400, "height":200}.

The form 'name' property must follow the naming conventions for html elements - no embedded spaces, etc.

An example of the addForm command:

mdi.addForm({"name":"form1", "url":"child1.htm",
"width":400, "height":200});

A window is created and opened by the form(..).show() command. The show() command returns the internal name of the window which is used for future manipulations of the window.

An example of creating a window:

var windowName = mdi.form('form1').show();

If you want to close a window:

mdi.window(windowName).close();

The basic architecture of an MDIware application is of a parent web page with multiple child windows that are instantiated as iframes by the MDIware library. Each child window is simply another web page in an iframe of the parent page.

Each iframe is represented by a window object in the MDIware array of windows.

The example web pages are in html and javascript for simplicity. MDIware works just as well with php or aspx pages since it is all client-side javascript.

Window Types

There are a variety of window types. The window type is determined by the MDI form object and the show() command.

Standard window	A standard window is created by using the form(formName).show() command. A new window is initially shown at the top of the z-order. The form(formName).show() command returns an internally generated name for the new window. This windowName can be used in subsequent actions to modify or close the window. Example: var windowName; mdi.addForm({"name":"sample", "url":"sample.htm", "title":"Sample"}); windowName=mdi.form('sample').show(); Note: You can add an optional parameter which is the modal property of the window. For example, mdi.form('sample').show(true) will open a window that is modal. No other window can gain focus when a modal window is open.
Attached window	An attached window is created by using a variation of the form show command called 'showAttached(attachedToWindowName)'. The showAttached command requires the name of the 'attached to' window to be passed as a parameter. An attached window is always shown at a higher z-index than the window it is attached to. When the 'attached to' window is closed the 'attached' window will be closed also. Attached windows are used often as dialog boxes such as a 'find' or 'file save' dialog in a text editor. Example: var windowName; mdi.addForm({"name":"form1", "url":"window1.htm", "title":"standard window"}); mdi.addForm({"name":"form2", "url":"window2.htm", "title":"attached window"}); windowName=mdi.form('form1').show(); mdi.form('form2').showAttached(windowName); Note: You can add an optional second parameter which is the modal property of the attached window. For example, mdi.form('form2').showAttached(windowName, true) will open an attached window that is modal relative to the window it is attached to.
Always on top	An always-on-top window is always at the top of the window stack. An always-on-top window is created by by setting the 'alwaysOnTop':true property of a form object. Example: var windowName; mdi.addForm({"name":"test", "url":"test.htm", "title":"AlwaysTopMost", "alwaysOnTop":true}); mdi.form('test').show(windowName);
Message Box	A message box is a special window that returns a single value when the user clicks one of the message box buttons. A message box is modal relative to the window that opened it. The msgBox command requires the inclusion of the MDIwareHooks.js file in the child window that uses the msgBox. Example: msgBox(title, Message, {"button1":"Ok", "button2":"Cancel"}, callBack); function callBack(retValue) { if (retValue == 'button1') { alert('Ok selected'); etc.... } }

Inter Window Communication

The multiple windows are managed by an MDIware object (named 'mdi') instantiated in the parent web page.

Each of these windows, child and parent, are separate web pages that typically need to communicate with each other.

Child to Parent Communication

The child window has access to most of the parent window's data and functions by prefacing the data or function name with 'parent.' As a security precaution, most browsers allow child-to-parent communication only when the child is from the same domain as the parent.

Often, a child window needs to use an mdi function. For instance, the child window may want to change its caption, change its size, close itself or open another window.

From a child window simply preface the mdi command with 'parent.'

For example, as a child window I may want to change my window title to "Ready"

// First I need to get my unique window name from MDIware.
// This is how a MDIware window accesses its unique internal name.
var myName = parent.mdi.windowName(window);

parent.mdi.window(myName).title('Ready');

Parent to Child Communication

The parent web page cannot directly access the functions and content of a MDIware window. One method for parent access is to have the child window pass an interface to the parent. The interface contains pointers to functions in the child window that the child window allows the parent to use. This method gives the child window control over which of its functions and data are exposed to the larger application.

There are functions in the MDIware library to help manage each window's interface object.

For example, suppose that the parent web page wants to access an input field named 'firstName' in the child window.

This example will require code in the parent window and in the child window.

Child window web page Code

//First we will create an interface object
var interface = new Object();

//Then we create an interface function that gets the contents of the 'firstName' field.

    interface.getFirstName = function(){
        return document.getElementById('firstName').value;
    }

//Finally, we register our interface with the parent.

var myWindowName = parent.mdi.windowName(window);
parent.mdi.registerWindowInterface(myWindowName, interface);

Parent web page Code

//Assume the parent window saved the name of the child when it was opened.

var nameOfChildWindow; //we saved this when we opened the child window

// get the window containing the 'firstName' text box
var win = mdi.window(nameOfChildWindow);

// get the windows interface object that was registered in the child code block
var interface = win.getWindowInterface();
// then call the getFirstName function to get the contents
var firstName = interface.getFirstName();
alert(firstName);

MDIwareHooks.js

Communication between windows is a common theme when programming so we have constructed a javascript file, MDIwareHooks.js, to eliminate much of the busy work. Include MDIwareHooks.js in the head of your child window forms.

If we redo the 'Parent-to-Child' example above it becomes much cleaner when including the MDIwareHooks.js file.

The child window code simplifies most - all we need to do is include the MDIwareHooks.js in the head section.

Child window web page Code

Parent web page Code

//Assume the parent window saved the name of the child when it was opened.

var nameOfChildWindow; //we saved this when we opened the child window

// get the window containing the 'firstName' text box
var win = mdi.window(nameOfChildWindow);

// get the windows interface object that was registered in MDIwareHooks.js
var interface = win.getWindowInterface();
// then call the interface.val function to get the contents
var firstName = interface.val('#firstName')
alert(firstName);

Message Box

MDIware includes a message box that can be used by any child window to get a user's response.

The message box requires communication between the child window and the parent form. As in the communication example above, we will include the MDIwareHooks.js file in the child window's code. The interface object in MDIwareHooks.js will be used by the MDIware object in the parent form to send the user's message box choice back to the child window.

Child window web page Code

//In the child window we will write a function that will receive the user's response.
//We will call the function 'responseFN'.

function responseFN(response)
{
    switch(response)
    {
        case 'buttOk':
        code to process Ok ....
        break;
        case 'buttCancel':
        code to process Cancel ....
        break;
    }
}
//msgBox Syntax:
//msgBox(title, message, buttons, callBack)
//The msgBox() function REQUIRES THE INCLUSION of MDIwareHooks.js

//Finally, to display a message box we execute the following line of code.

    msgBox('Careful',
        'Do you want to save your work?',
         {buttOk:'Ok', buttCancel:'Cancel'}, responseFN);

MDIware is a professional javascript library that simplifies the creation and management of multiple browser windows and message boxes, including modal, dialog and always-on-top windows. MDIware also provides a framework for inter-window communication. Above all, MDIware is elegantly simple in design and usage.

MDIware™ - A Multiple Document Interface for the Cloud