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.

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.

EXAMPLE

MySite.MyPageWidgetClass.instanceMethods ({
  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)
          ;
        }
      }
    );
  }
});

An object, specifying the node into which the loaded HTML should be injected, and how it should be injected (e.g. 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.32.1.1.1. node

3.32.1.1.2. injectMode

3.32.1.1.3. alwaysReplace

3.32.1.1.4. rootNodeId

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.

.

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

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

3.32.1.3.1. callback

EXAMPLE

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

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

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

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.

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

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.

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.

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.

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
}

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.

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.

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.

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.

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.

An integer, specifying the width of the document area of the popup window (i.e. 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.

An integer, specifying the height of the document area of the popup window (i.e. 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.

A string, specifying the name of the popup window.

The value of this property should be a valid JavaScript identifier (i.e. 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.

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

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

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.

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.

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.

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.

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.

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.

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.