UIZE JavaScript Framework

MODULES Uize.Widget.Page

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 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.

1.1. Examples

The following example pages are good showcases for the Uize.Widget.Page module...

Decorated Confirm Dialog - Why settle for ugly JavaScript alert and confirm dialogs when you can have stylish inline HTML dialogs, themed to your choosing with a bit of CSS!

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Widget.Page module...

SEARCH

1.2. Implementation Info

The Uize.Widget.Page module defines the Uize.Widget.Page class, which is a subclass of Uize.Widget.

INHERITANCE CHAIN

Uize.Class −> Uize.Widget −> Uize.Widget.Page

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

INSTANCE METHODS

flushAjaxCache | launchPopup | loadHtml | loadHtmlIntoNode | performAjax | useDialog | wireDeferredLinks

STATE PROPERTIES

confirmDialog | deferredLinks | dialogProperties | linkBatchSize

STATIC METHODS

Uize.Widget.Page.launchPopup

STATIC PROPERTIES

Uize.Widget.Page.deferredLinks | Uize.Widget.Page.linkBatchSize

1.2.2. Features Overridden in This Module

The features listed in this section have been overridden in this module.

The module that an overridden feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

showConfirm | showInform | valueOf | wireUi

STATE PROPERTIES

idPrefix

STATIC METHODS

Uize.Widget.Page.valueOf

STATIC PROPERTIES

Uize.Widget.Page.moduleName | Uize.Widget.Page.nonInheritableStatics

1.2.3. Features Inherited From Other Modules

The features listed in this section have been inherited from other modules.

The module that an inherited feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

addChild | addChildren | ajax | buildHtml | callInherited | childId | confirm | displayNode | fire | flushNodeCache | get | getContainer | getHtml | getInherited | getNode | getNodeStyle | getNodeValue | getProvider | globalizeNode | inform | injectNodeHtml | insertOrWireUi | insertUi | is | isMet | kill | localize | met | nodeId | onChange | once | removeChild | removeNode | removeUi | set | setInherited | setNodeClipRect | setNodeInnerHtml | setNodeOpacity | setNodeProperties | setNodeStyle | setNodeValue | showNode | toggle | unmet | unwire | unwireNode | unwireNodeEventsByMatch | unwireUi | updateUi | whenever | wire | wireNode

STATE PROPERTIES

built | busy | busyInherited | children | container | enabled | enabledInherited | html | idPrefixConstruction | insertionMode | localized | name | nodeMap | wired

STATIC METHODS

Uize.Widget.Page.alphastructor | Uize.Widget.Page.declare | Uize.Widget.Page.doMy | Uize.Widget.Page.dualContextMethods | Uize.Widget.Page.dualContextProperties | Uize.Widget.Page.fire | Uize.Widget.Page.get | Uize.Widget.Page.getBlankImageUrl | Uize.Widget.Page.instanceMethods | Uize.Widget.Page.instanceProperties | Uize.Widget.Page.mixins | Uize.Widget.Page.omegastructor | Uize.Widget.Page.set | Uize.Widget.Page.singleton | Uize.Widget.Page.spawn | Uize.Widget.Page.stateProperties | Uize.Widget.Page.staticMethods | Uize.Widget.Page.staticProperties | Uize.Widget.Page.subclass | Uize.Widget.Page.toggle | Uize.Widget.Page.treeInheritedStateProperties | Uize.Widget.Page.unwire | Uize.Widget.Page.wire

STATIC PROPERTIES

Uize.Widget.Page.busyInherited | Uize.Widget.Page.enabledInherited | Uize.Widget.Page.isWired | Uize.Widget.Page.pathToResources

1.2.4. Modules Directly Under This Namespace

1.2.5. Unit Tests

There is no dedicated unit tests module for the Uize.Widget.Page module.

2. Key Features

2.1. 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 guide JavaScript Widgets and see under the section Page Widget.

2.2. Hook Methods

The Uize.Widget.Page class supports a number of "hook methods" that are primarily of interest to developers of the UIZE JavaScript Framework and are not intended to be used in applications, and that are only public because they form an interface between separate modules.

These hook methods include the loadHtml, showConfirm, and showInform instance methods.

3. Instance Methods

3.1. addChild

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.2. addChildren

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.3. ajax

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.4. buildHtml

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.5. callInherited

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.6. childId

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.7. confirm

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.8. displayNode

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.9. fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.10. flushAjaxCache

A stub implementation of the flushAjaxCache instance method that should be overridden by page widget subclasses to flush the cache of Ajax requests.

This method should expect to receive the requestOrUrl parameter expected by Uize.Comm.flushCache().

IMPLEMENTATION INFO

this feature was introduced in this module

3.11. flushNodeCache

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.12. get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.13. getContainer

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.14. getHtml

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.15. getInherited

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.16. getNode

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.17. getNodeStyle

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.18. getNodeValue

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.19. getProvider

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.20. globalizeNode

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.21. inform

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.22. injectNodeHtml

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.23. insertOrWireUi

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.24. insertUi

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.25. is

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.26. isMet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.27. kill

Inherited from Uize.Widget, but introduced in Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Class)

3.28. 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 = 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.

IMPLEMENTATION INFO

this feature was introduced in this module

3.29. loadHtml

Provides a hook to support the implementation of the loadHtmlIntoNode instance method.

SYNTAX

myPageWidget.loadHtml (htmlParamsOBJ,directivesOBJorCallbackFUNC);

The loadHtml method, as implemented in this class, is only a stub implementation - you should override this method in your own page widget subclass to provide an implementation that will actually perform the HTML loading.

3.29.1. Parameters

Any implementation of the loadHtml method should expect to receive the following two parameters...

3.29.1.1. htmlParamsOBJ

An object, providing data that can be used by the HTML generator.

The htmlParamsOBJ may contain any number of arbitrary properties that are used by the HTML generator in generating its HTML output, so the properties supported will depend entirely upon the particular HTML generator.

3.29.1.2. directivesOBJorCallbackFUNC

An object, providing directives that can be used to qualify how HTML is generated by the HTML generator, or a function that should be called once the HTML has been generated.

If an object is specified for the directivesOBJorCallbackFUNC parameter, it can contain a callback property that specifies the function that should be called once the HTML has been generated. The callback function should expect to receive a single string parameter, being the generated HTML.

3.29.2. Example Usage

EXAMPLE

myPageWidget.loadHtml (
  {
    control:'searchresults',
    keywords:'dog puppy hound canine',
    sort:'recent',
    results:20
  },
  function (_html) {
    myPageWidget.setNodeInnerHtml ('searchResultsPane',_html);
  }
);

3.29.3. loadHtml Implementation

3.29.3.1. Example Implementation

EXAMPLE

MySite.MyPageWidgetClass.prototype.loadHtml = function (_htmlParams,_directives) {
  var m = this;
  if (typeof _directives != 'object' || !_directives)
    _directives = {callback:_directives}
  ;
  m.ajax (
    Uize.copyInto ({service:'getcontrol'},_htmlParams),
    {
      cache:'cache' in _directives ? _directives.cache : 'never',
      callbackSuccess:function (_responseJson) {
        _responseJson.success &&
          (_directives.callback || Object) (responseJson.componentData)
        ;
      }
    }
  );
};

NOTES

this method is one of several hook methods
see the related loadHtmlIntoNode instance method

IMPLEMENTATION INFO

this feature was introduced in this module

3.30. loadHtmlIntoNode

Lets you dynamically load HTML and inject that HTML into the specified node.

SYNTAX

myPageWidget.loadHtmlIntoNode (
  injectionParamsOBJ,htmlParamsOBJ,loaderDirectivesOBJorCallbackFUNC
);

With a suitable implementation of the companion loadHtml instance method, the loadHtmlIntoNode method can be used to load HTML from the server using Ajax and then inject that HTML into some DOM node on the page. How HTML is loaded is entirely dependent on the loadHtml method's implementation.

3.30.1. Parameters

3.30.1.1. injectionParamsOBJ

An object, specifying the node into which the loaded HTML should be injected, and how it should be injected (eg. inserted above existing contents, inserted after existing contents, replacing existing contents, etc.).

The injectionParamsOBJ parameter's value should be an object of the form...

{
  node          : nodeNameSTR,
  injectMode    : injectModeSTR,      // optional
  alwaysReplace : alwaysReplaceBOOL,  // optional
  rootNodeId    : rootNodeIdSTR       // optional
}

The injectionParamsOBJ object supports the following properties...

3.30.1.1.1. node

A node blob, specifying the node (or nodes) into which the loaded HTML should be injected.

NOTES

required
3.30.1.1.2. injectMode

A string, specifying how the HTML should be injected into the node(s) specified by the node property.

The value specified for this property can be any value that can be specified for the injectModeSTR parameter of the Uize.Dom.Basics.injectHtml static method and its sister injectNodeHtml instance method of the Uize.Widget class.

NOTES

optional
the default value for this property is 'inner replace', except when the node is the document body (ie. a reference to the document.body object), in which case the property defaults to 'inner bottom'
3.30.1.1.3. alwaysReplace

A boolean, indicating whether or not any HTML that is already in the page and that is considered equivalent to the HTML being injected should be replaced.

A DOM node in the page will be considered equivalent to the HTML being injected if its id is identical to the value of the optional rootNodeId property of the injectionParamsOBJ object. If HTML exists that is considered equivalent, then it will be replaced with the new loaded HTML if the value true is specified for the alwaysReplace property, or if the alwaysReplace property is omitted from the injectionParamsOBJ object (so, it defaults to true).

NOTES

optional
the default value for this property is true
3.30.1.1.4. rootNodeId

A string, specifying the id of a node that should be considered equivalent to the HTML being injected, and that should not be replaced if the value false is specified for the alwaysReplace property of the injectionParamsOBJ object.

If no DOM node exists in the document with the id specified in the rootNodeId property, then the loaded HTML will always be injected. The loaded HTML will only not be injected if a DOM node with the id specified in the rootNodeId property does exist in the document and the value false is specified for the alwaysReplace property.

NOTES

optional
the default value for this property is undefined

3.30.1.2. htmlParamsOBJ

An object, providing data that can be used by the HTML generator.

The htmlParamsOBJ may contain any number of arbitrary properties that are used by the HTML generator in generating its HTML output, so the properties supported will depend entirely upon the particular HTML generator.

3.30.1.3. loaderDirectivesOBJorCallbackFUNC

.

{
  callback : callbackFUNC,
  ... ... ...
  ... ... ...
  ... ... ...
}

When the value of the loaderDirectivesOBJorCallbackFUNC parameter is an object, the object supports the following properties...

3.30.1.3.1. callback

.

3.30.2. Loading is Implemented Elsewhere

It is important to note that the loadHtmlIntoNode method does not actually perform the loading of the HTML itself - instead, it defers to the implementation of the companion loadHtml hook method.

3.30.3. Examples

3.30.3.1. Default Injection, No Callback

EXAMPLE

myPageWidget.loadHtmlIntoNode (
  {node:'searchResultsPane'},
  {
    control:'searchresults',
    keywords:'dog puppy hound canine',
    sort:'recent',
    results:20
  }
);

3.30.3.2. Inner Bottom Injection, With Callback

EXAMPLE

myPageWidget.loadHtmlIntoNode (
  {
    node:'searchResultsPane',
    injectMode:'inner bottom'
  },
  {
    control:'searchresults',
    keywords:'dog puppy hound canine',
    sort:'recent',
    results:20,
    page:2
  },
  function () {
    // perform animated reveal effect
  }
);

IMPLEMENTATION INFO

this feature was introduced in this module

3.31. localize

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.32. met

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.33. nodeId

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.34. onChange

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.35. once

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.36. performAjax

A stub implementation of the performAjax instance method that should be overridden by page widget subclasses in order to provide an implementation of Ajax communication.

An implementation of Ajax communication, provided by an implementation of the performAjax method in a page widget, will be used to handle Ajax requests initiated by widget instances on the page widget's widget tree. The stub implementation provided in this class does nothing. An implementation that you provide in your own page widget subclass should expect to receive the two parameters passed by the ajax instance method of the Uize.Widget class.

IMPLEMENTATION INFO

this feature was introduced in this module

3.37. removeChild

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.38. removeNode

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.39. removeUi

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.40. set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.41. setInherited

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.42. setNodeClipRect

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.43. setNodeInnerHtml

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.44. setNodeOpacity

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.45. setNodeProperties

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.46. setNodeStyle

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.47. setNodeValue

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.48. showConfirm

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

NOTES

this method is one of several hook methods
see also the companion showInform hook method

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Widget)

3.49. showInform

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

NOTES

this method is one of several hook methods
see also the companion showConfirm hook method

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Widget)

3.50. showNode

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.51. toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.52. unmet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.53. unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.54. unwireNode

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.55. unwireNodeEventsByMatch

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.56. unwireUi

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.57. updateUi

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.58. 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.58.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.58.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.58.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.58.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.58.2.1. widgetProperties

An object, specifying the values of state 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 us 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 dialog 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 state 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.58.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.58.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.58.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.58.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.58.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.58.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.58.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.58.3. An Example

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

EXAMPLE

myWidget.callInherited ('useDialog') ({
  widgetClassName:'MyCompanySite.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 MyCompanySite.DialogConfirm is being used for the dialog widget, and the various widget properties that are specified in the widgetProperties property are state properties of the MyCompanySite.DialogConfirm class. This example is essentially using a dynamically loaded dialog widget class for displaying a decorated confirmation dialog that is implemented using HTML.

IMPLEMENTATION INFO

this feature was introduced in this module

3.59. valueOf

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)

IMPLEMENTATION INFO

3.60. whenever

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.61. wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.62. wireDeferredLinks

IMPLEMENTATION INFO

this feature was introduced in this module

3.63. wireNode

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

3.64. wireUi

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Widget)

4. Static Methods

4.1. Uize.Widget.Page.alphastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.2. Uize.Widget.Page.declare

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.3. Uize.Widget.Page.doMy

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.4. Uize.Widget.Page.dualContextMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.5. Uize.Widget.Page.dualContextProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.6. Uize.Widget.Page.fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.7. Uize.Widget.Page.get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.8. Uize.Widget.Page.getBlankImageUrl

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)
this static feature is inherited by subclasses

4.9. Uize.Widget.Page.instanceMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.10. Uize.Widget.Page.instanceProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.11. 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.11.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.11.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.11.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.11.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.11.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 or undefined is specified, then the default value 'popupWindow' will be used. The special value '' (empty string) will allow multiple popup windows to be opened, without having to worry about popup window reuse, and without having to programmatically generate unique names for each window opened.

4.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.11.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.

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

4.12. Uize.Widget.Page.mixins

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.13. Uize.Widget.Page.omegastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.14. Uize.Widget.Page.set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.15. Uize.Widget.Page.singleton

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.16. Uize.Widget.Page.spawn

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)
this static feature is inherited by subclasses

4.17. Uize.Widget.Page.stateProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.18. Uize.Widget.Page.staticMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.19. Uize.Widget.Page.staticProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.20. Uize.Widget.Page.subclass

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.21. Uize.Widget.Page.toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.22. Uize.Widget.Page.treeInheritedStateProperties

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)
this static feature is inherited by subclasses

4.23. Uize.Widget.Page.unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.24. Uize.Widget.Page.valueOf

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.25. Uize.Widget.Page.wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5. State Properties

5.1. built

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.2. busy

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.3. busyInherited

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.4. children

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.5. 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.5.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

IMPLEMENTATION INFO

this feature was introduced in this module

5.6. container

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.7. deferredLinks

IMPLEMENTATION INFO

this feature was introduced in this module

5.8. dialogProperties

IMPLEMENTATION INFO

this feature was introduced in this module

5.9. enabled

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.10. enabledInherited

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.11. html

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.12. idPrefix

This class inherits the idPrefix state 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.

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Widget)

5.13. idPrefixConstruction

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.14. insertionMode

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.15. linkBatchSize

IMPLEMENTATION INFO

this feature was introduced in this module

5.16. localized

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.17. name

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.18. nodeMap

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

5.19. wired

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)

6. Static Properties

6.1. Uize.Widget.Page.busyInherited

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)
this static feature is inherited by subclasses

6.2. Uize.Widget.Page.deferredLinks

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

6.3. Uize.Widget.Page.enabledInherited

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)
this static feature is inherited by subclasses

6.4. Uize.Widget.Page.isWired

Inherited from Uize.Widget.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Widget, first introduced in Uize.Widget)
this static feature is inherited by subclasses

6.5. Uize.Widget.Page.linkBatchSize

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

6.6. Uize.Widget.Page.moduleName

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.7. Uize.Widget.Page.nonInheritableStatics

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is not inherited by subclasses

6.8. Uize.Widget.Page.pathToResources

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses