MODULES Uize.Widget.Page
SEARCHEXAMPLESVIEW SOURCE CODE

1. Introduction

The Uize.Widget.Page class implements the page widget (the main controller for a page), supporting widget adoption, dialog sharing, popups, and more.

DEVELOPERS: Chris van Rensburg, Ben Ilegbodu

The Uize.Widget.Page module defines the Uize.Widget.Page widget class, a subclass of Uize.Widget. The page widget provides an environment and services that can be relied upon by child widgets in its tree. Use this base class as the superclass for page widget classes that you will develop for your own Web site projects.

2. Widget Adoption

This class implements a widget adoption mechanism that allows child widgets to be declared in the page's markup using a purely declarative syntax (ie. requiring no JavaScript to be previously loaded).

For more information on this feature, and for a discussion of some of the other features of the Uize.Widget.Page class, consult the explainer JavaScript Widgets and see under the section Page Widget.

3. Instance Methods

3.1. launchPopup

For convenience, the Uize.Widget.Page.launchPopup static method is also mapped as the instance method launchPopup.

SYNTAX

windowOBJ = myPageWidget.launchPopup (popupPropertiesOBJ);

The launchPopup instance method is fully equivalent to the Uize.Widget.Page.launchPopup static method, but its availability as an instance method is convenient for implementing page widget code, or for implementing widgets that are expected to be used within the context of a widget tree with a page widget at the root.

EXAMPLE

// using the static method
Uize.Widget.Page.launchPopup ({name:'window1',url:'http://www.wikipedia.org'});

// calling the instance method on a page widget instance
page = new Uize.Widget.Page;
page.launchPopup ({name:'window2',url:'http://www.zazzle.com'});

// using callInherited to access instance method of root page widget from child
var widget = page.addChild ('myChildWidget',Uize.Widget);
widget.callInherited ('launchPopup') ({name:'window3',url:'http://www.uize.com'});

For an in-depth discussion of the features of the launchPopup instance method, consult the reference for the Uize.Widget.Page.launchPopup static method.

3.2. useDialog

Lets you conveniently use a dialog widget that may need to be dynamically loaded.

SYNTAX

myPageWidget.useDialog (paramsOBJ);

Both the widget class for the dialog as well as its HTML markup can be loaded dynamically. The useDialog method takes care of loading the dialog widget class module and HTML, if necessary. Also, this method makes it easy for the same dialog to be reused multiple times - from within the same code or across different modules of code. Once a dialog has been loaded and used for the first time, then subsequent uses of the dialog will incur no additional load cost. Examples of dialogs that are suitable for use with this method are: a confirmation dialog, a media browser dialog, a file uploader dialog, a date picker dialog, a color picker dialog, a link-to-this dialog, etc.

3.2.1. Contract

In order for a dialog widget class to be compatible with the useDialog method, it must comply with a specific contract (or interface).

3.2.1.1. Submission Complete

A dialog widget class to be used with this method should be a subclass of the Uize.Widget.Dialog class (or one of its subclasses), and should implement a Submission Complete event.

This event should be fired when the dialog has finished all its processing and has produced a result that can be delivered to the code that is using the dialog. This means that the Submission Complete event may fire some time after the user either clicks the dialog's ok button or otherwise interacts with the contents of the dialog so that it triggers submission. The dialog class may need to perform asynchronous processing to complete the submission action. The event object for the Submission Complete event should contain a result property, and the value of this property will be relayed to the handler function specified in the submitHandler property of the paramsOBJ parameter (see below).

3.2.1.2. Close and Cancel

The handler function specified in the submitHandler property of the paramsOBJ parameter will not be executed when the user closes the dialog by clicking the close or cancel button, unless you deliberately code your dialog class to do this.

There may be cases where it is desirable (such as with a confirmation dialog) for the close and cancel buttons to fire a Submission Complete event, with a false or "no" value for the result. In such cases, your dialog class can listen on its own Close and Cancel events in order to fire the Submission Complete event. A good example of this can be found in the Uize.Widget.Dialog.Confirm module.

3.2.2. paramsOBJ

The paramsOBJ parameter lets you specify parameters for the useDialog method, and its value should be an object that may contain the following properties...

3.2.2.1. widgetProperties

An object, specifying the values of set-get properties of the dialog widget that will be set on the dialog widget right before it is displayed.

The widgetProperties property's value should be an object of the form...

{
  name:dialogWidgetNameSTR, // REQUIRED!!!
  parent:parentWidgetOBJ,   // optional, defaults to page widget
  idPrefix:idPrefixSTR,     // optional, constructed if not specified
  ... ... ...
  ... ... ...
  ... ... ...
}

NOTES

The value specified for the required "name" property will be used as the child widget name for the dialog widget.
The optional "parent" property allows you to attach the dialog widget as the child of a widget other than the page widget. If not specified (which is most of the time), the diaog widget will have the page widget as its parent.
The optional "idPrefix" property lets you explicitly specify the idPrefix for the dialog widget. Usually you will want to just leave it up to the useDialog method to construct the idPrefix for you, based upon the idPrefix of the dialog widget's parent and the name of the dialog widget (as specified in the "name" property mentioned earlier).

Beyond the "name", "parent", and "idPrefix" properties, values can be specified for any of the set-get properties supported by the class of the dialog widget. This is useful for reuse of dialogs, where on repeat use you may wish to change state.

3.2.2.2. component

An object, defining the parameters for a server side component that should be accessed - through an Ajax request - for providing the HTML markup for the dialog.

The component property's value should be an object of the form...

{
  name:componentNameSTR,
  params:componentParamsOBJ
}

When no component property is specified, then the dialog widget's HTML will be expected to be already in the page, or it will be the responsibility of the dialog's widget class to build the HTML for insertion into the page.

3.2.2.3. widgetClassName

A string, specifying the name of the widget class that should be used for creating the instance of the dialog widget.

The widget class is specified as a string, precisely because the class may not yet be loaded (you can't reference a class that isn't defined). The class name is used by the module loader mechanism to dynamically load in the widget class module for the dialog.

3.2.2.4. widgetEventHandlers

An object, specifying handlers for events of the dialog widget that should be wired up when the widget is first instantiated.

The widgetEventHandlers property's value should be an object of the form...

{
  event1Name:event1HandlerSTRorFN,
  event2Name:event2HandlerSTRorFN,
  ...
  eventNName:eventNHandlerSTRorFN
}

3.2.2.5. submitHandler

A function, specifying the callback handler that will be executed when the user submits the dialog by clicking on its ok button, or otherwise interacts with the contents of the dialog so that it triggers submission.

The handler function that you specify for this property can expect to receive a single parameter, being the result of the submission action. The value of this result will depend on the specific dialog widget class being used - in some cases it may be a simple type value (such as a boolean), while in other cases it may be an object containing multiple properties.

3.2.2.6. closeHandler

A function, specifying the callback handler that will be executed if the user closes the dialog by clicking the close button.

The handler function that you specify for this property can expect to receive a single parameter, being the event object originating from the dialog.

3.2.2.7. cancelHandler

A function, specifying the callback handler that will be executed if the user dismisses the dialog by clicking the cancel button.

The handler function that you specify for this property can expect to receive a single parameter, being the event object originating from the dialog.

3.2.2.8. dismissHandler

A function, specifying the callback handler that will be executed if the user dismisses the dialog by clicking either the close or cancel button.

The handler function that you specify for this property can expect to receive a single parameter, being the event object originating from the dialog.

3.2.3. An Example

To better understand how the useDialog method is used, let's consider an example...

EXAMPLE

myWidget.callInherited ('useDialog') ({
  widgetClassName:'UizeDotCom.DialogConfirm',
  widgetProperties:{
    name:'confirmDialog',
    title:'Are you sure?',
    message:'Would you like to delete this product?',
    mode:'confirm',
    state:'confirm',
    okText:'DELETE',
    cancelText:'NOOOOOOOOO!!!!'
  },
  submitHandler:function (_confirmed) {
    if (_confirmed) {
      alert ('now your product will get deleted');
      // code to delete the product
    }
  }
});

In the above example, the callInherited instance method of the widget myWidget is being used to get a caller for the useDialog instance method of the page widget. It is assumed, in this example, that myWidget is somewhere on a widget tree with a page widget instance at the root. The widget class UizeDotCom.DialogConfirm is being used for the dialog widget, and the various widget properties that are specified in the widgetProperties property are set-get properties of the UizeDotCom.DialogConfirm class. This example is essentially using a dynamically loaded dialog widget class for displaying a decorated confirmation dialog that is implemented using HTML.

4. Static Methods

4.1. Uize.Widget.Page.launchPopup

Lets you launch content in a popup window, allowing you to specify properties for that popup window, such as width, height, toolbar, scrollbars, etc.

SYNTAX

windowOBJ = Uize.Widget.Page.launchPopup (popupPropertiesOBJ);

EXAMPLE

Uize.Widget.Page.launchPopup ({url:'http://www.wikipedia.org',width:800,height:600});

The above example will launch the Wikipedia Web site in a popup window named popupWindow, and whose document area is sized to 800x600.

4.1.1. popupPropertiesOBJ

The popupPropertiesOBJ parameter lets you specify various properties for the popup window, and its value should be an object that may contain the following properties...

4.1.1.1. url

A string, specifying the URL of the document that should be loaded into the popup window.

If no URL is specified, then a Blank Popup Window will be launched.

4.1.1.2. width

An integer, specifying the width of the document area of the popup window (ie. not the outside width, so excluding browser chrome).

When no value is specified for this property, or if the value 0, null, or undefined is specified, then the default value of 850 will be used.

4.1.1.3. height

An integer, specifying the height of the document area of the popup window (ie. not the outside height, so excluding browser chrome).

When no value is specified for this property, or if the value 0, null, or undefined is specified, then the default value of 600 will be used.

4.1.1.4. name

A string, specifying the name of the popup window.

The value of this property should be a valid JavaScript identifier (ie. no special characters or delimeters that would break an identifier). If a window is already open by the name specified in the name property, then it will be reused (see Reusing Windows). When no value is specified for this property, or if the value null, undefined, or '' (empty string) is specified, then the default value 'popupWindow' will be used.

4.1.1.5. left

An integer, specifying the screen coordinate for the left edge of the popup window.

When no value is specified for this property, or if the value null or undefined is specified, then the popup window will be centered horizontally (see Automatic Centering).

4.1.1.6. top

An integer, specifying the screen coordinate for the top edge of the popup window.

When no value is specified for this property, or if the value null or undefined is specified, then the popup window will be centered vertically (see Automatic Centering).

4.1.1.7. toolbar

A string, boolean, or number, specifying whether or not the toolbar should be displayed for the popup window.

For convenience, the value of this property can be of multiple types (see Switch Property Values below). When no value is specified for this property, or if the value null or undefined is specified, then the default value 'no' will be used.

4.1.1.8. location

A string, boolean, or number, specifying whether or not the location bar should be displayed for the popup window.

For convenience, the value of this property can be of multiple types (see Switch Property Values below). When no value is specified for this property, or if the value null or undefined is specified, then the default value 'no' will be used.

4.1.1.9. directories

A string, boolean, or number, specifying whether or not the directories bar should be displayed for the popup window.

In some browsers, the directories bar is known as the personal toolbar and may contain personal bookmarks. For convenience, the value of this property can be of multiple types (see Switch Property Values below). When no value is specified for this property, or if the value null or undefined is specified, then the default value 'no' will be used.

4.1.1.10. status

A string, boolean, or number, specifying whether or not the status bar should be displayed for the popup window.

The status bar is usually displayed at the bottom of the browser window. For some browsers, it is not possible to suppress the status bar, so this property may essentially be ignored in such cases. For convenience, the value of this property can be of multiple types (see Switch Property Values below). When no value is specified for this property, or if the value null or undefined is specified, then the default value 'no' will be used.

4.1.1.11. menubar

A string, boolean, or number, specifying whether or not the menu bar should be displayed for the popup window.

The menu bar is usually displayed at the top of the browser window, underneath the titlebar. For convenience, the value of this property can be of multiple types (see Switch Property Values below). When no value is specified for this property, or if the value null or undefined is specified, then the default value 'no' will be used.

4.1.1.12. scrollbars

A string, boolean, or number, specifying whether or not scrollbars should be displayed for the popup window.

For convenience, the value of this property can be of multiple types (see Switch Property Values below). When no value is specified for this property, or if the value null or undefined is specified, then the default value 'yes' will be used.

4.1.1.13. resizable

A string, boolean, or number, specifying whether or not the popup window should be resizable by the user.

For convenience, the value of this property can be of multiple types (see Switch Property Values below). When no value is specified for this property, or if the value null or undefined is specified, then the default value 'yes' will be used.

4.1.2. Switch Property Values

For the switch properties toolbar, location, directories, status, menubar, scrollbars, and resizable, values can be specified as string, boolean, or number.

Boolean and number type values are resolved to the string values 'yes' or 'no'. The boolean value true and the number value 1 are resolved to 'yes', and the boolean value false and the number value 0 are resolved to 'no'. Additionally, the string values 'on', 'true', and '1' are resolved to 'yes', and the string values 'off', 'false', and '0' are resolved to 'no'.

4.1.3. Automatic Centering

The popup window is automatically centered if positioning is not specified by the left and/or top properties.

When no value is specified for the left property, then the popup window will be centered horizontally. Similarly, when no value is specified for the top property, then the popup window will be centered vertically. If neither left nor top are specified, then the popup window will be centered horizontally and vertically.

4.1.4. Blank Popup Window

When no value is specified for the url property, or if the value null, undefined, or '' (empty string) is specified, then a blank popup window will be launched.

A document can be written into a blank popup window by using the window object reference that is returned by the Uize.Widget.Page.launchPopup method, as in...

EXAMPLE

var
  popupWindow = Uize.Widget.Page.launchPopup ({width:350,height:100}),
  popupWindowDoc = popupWindow.document
;
popupWindowDoc.open ('text/plain');
popupWindowDoc.writeln ('HELLO, WORLD!');
popupWindowDoc.close ();

In the above example, a little popup window would be launched displaying the text "HELLO, WORLD!".

4.1.5. Reusing Windows

If a window is already open by the name specified in the name property, then it will be reused.

A reused window will be brought to the front (see Focusing of Popup Windows), but its properties will not be updated to the new property values specified in the popupPropertiesOBJ parameter. So, size, position, displaying of scrollbars, etc. will not be changed when a popup window is reused. If a value is specified for the url property, then the contents of the reused window will be replaced with the document from the specified URL. If no url is specified, then the contents of the reused window will not be disturbed.

4.1.6. Focusing of Popup Windows

Popup windows that are launched using the Uize.Widget.Page.launchPopup method are focused (brought to the front).

This is useful for reusing popup windows that may have become covered by other browser windows since first being launched.

VARIATION

windowOBJ = Uize.Widget.Page.launchPopup ();

When no popupPropertiesOBJ parameter is specified, then a blank popup window will be opened using default values for all the popupPropertiesOBJ properties.

5. Set-get Properties

5.1. confirmDialog

An object, allowing aspects of the confirm dialog to be configured by an application.

The object value for this property should be of the form...

{
  component:componentProfileOBJ, // optional
  widgetClassName:widgetClassNameSTR
}

5.1.1. Confirm Dialog Properties

The confirm dialog can be configured for an application using the following two properties...

component - A string, specifying the name of the server side component that should be loaded for building the confirm dialog's HTML. If no value is specified for the component property, then no component will be loaded from the server, and the confirm dialog's HTML will be expected to be already in the page, or it will be the responsibility of the confirm dialog's widget class to build the HTML for insertion into the page.
widgetClassName - A string, specifying the class name of the dialog widget that should be used for the confirm dialog. When no value is specified for the widgetClassName property, then the class Uize.Widget.Dialog.Confirm will be used as the default.

NOTES

the initial value is {} (empty object)
the value specified for this property will affect the behavior of the showConfirm and showInform instance methods

5.2. idPrefix

This class inherits the idPrefix set-get property from the Uize.Widget base class, but overrides the initial value to 'page'.

Therefore, an instance of the page widget that is created without specifying a value for this property will automatically get the value 'page'. You will generally only create one instance of this widget per page.

6. Hook Methods

These methods are primarily of interest to developers of the UIZE JavaScript Framework and are not intended to be used in applications. They are only public because they form an interface between separate modules.

6.1. showConfirm

Provides a hook to support the implementation of the confirm instance method of the Uize.Widget class.

NOTES

see also the companion showInform hook method

6.2. showInform

Provides a hook to support the implementation of the inform instance method of the Uize.Widget class.

NOTES

see also the companion showConfirm hook method