Class RapidContext.Widget.Wizard

.Widget.Wizard(attrs, …childopt) → {Widget}

The wizard widget class. Used to provide a sequence of pages, where the user can step forward and backward with buttons. Internally it uses a <div> HTML element containing Pane widgets that are hidden and shown according to the page transitions.

Constructor Summary
	`new Wizard(attrs, …childopt) → {Widget}` Creates a new wizard widget.

Method Summary
	`activatePage(indexOrPage)` Activates a new page and sends the `onchange` signal.
	`activePage() → {Widget}` Returns the active page.
	`activePageIndex()` Returns the active page index.
	`addAll(…child)` Adds one or more children to this widget.
	`addChildNode(child)` Adds a single child page widget to this widget.
	`addClass(…cls)` Adds the specified CSS class names to this HTML DOM node.
	`animate(opts)` Performs a visual effect animation on this widget.
	`blurAll()` Blurs (unfocuses) this DOM node and all relevant child nodes.
	`cancel()` Cancels the active page operation.
	`destroy()` The internal widget destructor function.
	`disable()` Disables this widget if it was previously enabled.
	`done()` Sends the wizard `onclose` signal.
	`enable()` Enables this widget if it was previously disabled.
	`getChildNodes() → {Array}` Returns an array with all child pane widgets.
	`hasClass(…cls) → {boolean}` Checks if this HTML DOM node has the specified CSS class names.
	`hide()` Hides this widget node if it was previously visible.
	`isDisabled() → {boolean}` Checks if this widget is disabled.
	`isHidden() → {boolean}` Checks if this widget node is hidden.
	`next()` Moves the wizard forward to the next page and sends the `onchange` signal.
	`previous()` Moves the wizard backward to the previous page and sends the `onchange` signal.
	`removeAll()` Removes all children to this widget.
	`removeChildNode(child)` Removes a single child DOM node from this widget.
	`removeClass(…cls)` Removes the specified CSS class names from this HTML DOM node.
	`setAttrs(attrs)` Updates the widget or HTML DOM node attributes.
	`setStyle(styles)` Updates the CSS styles of this HTML DOM node.
	`show()` Shows this widget node if it was previously hidden.
	`toggleClass(…cls) → {boolean}` Toggles adding and removing the specified CSS class names to and from this HTML DOM node.
	`uid() → {string}` Returns the unique identifier for this DOM node.

Event Summary
	`oncancel` Emitted when the user selects to cancel the page flow.
	`onchange` Emitted when a page transition is performed.
	`onclose` Emitted when the user has completed the page flow.

Constructor

new Wizard(attrs, …childopt) → {Widget}

Creates a new wizard widget.

Parameters:

Name Type Attributes Description

attrs

{Object}

the widget and node attributes

Properties

Name	Type	Attributes	Description
`hidden`	{boolean}	<optional>	the hidden widget flag, defaults to false

child {Pane} <optional>
<repeatable> the child Pane widgets

Returns:

{Widget} the widget DOM node

Examples:

JavaScript

var page1 = RapidContext.Widget.Pane({ pageTitle: "The first step" });
...
var page2 = RapidContext.Widget.Pane({ pageTitle: "The second step" });
...
var attrs = { style: { width: "100%", height: "100%" } };
var exampleWizard = RapidContext.Widget.Wizard(attrs, page1, page2);
var exampleDialog = RapidContext.Widget.Dialog({ title: "Example Dialog" }, exampleWizard);
RapidContext.Util.registerSizeConstraints(exampleDialog, "80%", "50%");

User Interface XML

<Dialog id="exampleDialog" title="Example Dialog" w="80%" h="50%">
  <Wizard id="exampleWizard" style="width: 100%; height: 100%;">
    <Pane pageTitle="The first step">
      ...
    </Pane>
    <Pane pageTitle="The second step">
      ...
    </Pane>
  </Wizard>
</Dialog>

Source:

RapidContext_Widget_Wizard.js, line 59

Extends

RapidContext.Widget

Methods

activatePage(indexOrPage)

Activates a new page and sends the onchange signal. If the page is moved forward, the old page must pass a form validation check, or nothing will happen.

Parameters:

Name	Type	Description
`indexOrPage`	{number\|Widget}	the page index or page DOM node

See:

#next
#previous

Source:

RapidContext_Widget_Wizard.js, line 235

activePage() → {Widget}

Returns the active page.

Returns:: {Widget} the active page, or null if no pages have been added
Source:: RapidContext_Widget_Wizard.js, line 207

activePageIndex()

Returns the active page index.

Returns:: the active page index, or -1 if no page is active
Source:: RapidContext_Widget_Wizard.js, line 221

addAll(…child)

Adds one or more children to this widget. This method will flatten any arrays among the arguments and ignores any null or undefined arguments. Any DOM nodes or widgets will be added to the end, and other objects will be converted to a text node first. Subclasses should normally override the addChildNode() method instead of this one, since that is the basis for DOM node insertion.

Parameters:

Name	Type	Attributes	Description
`child`	{string\|Node\|Array}	<repeatable>	the children to add

Inherited From:

RapidContext.Widget#addAll

Source:

RapidContext_Widget.js, line 570

addChildNode(child)

Adds a single child page widget to this widget. The child widget should be a RapidContext.Widget.Pane widget, or a new one will be created where it will be added.

Parameters:

Name	Type	Description
`child`	{Widget}	the page widget to add

Overrides:

RapidContext.Widget#addChildNode

Source:

RapidContext_Widget_Wizard.js, line 137

addClass(…cls)

Adds the specified CSS class names to this HTML DOM node.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to add

Inherited From:

RapidContext.Widget#addClass

Source:

RapidContext_Widget.js, line 333

animate(opts)

Performs a visual effect animation on this widget. This is implemented using the MochiKit.Visual effect package. All options sent to this function will be passed on to the appropriate MochiKit.Visual function.

Parameters:

Name Type Description

opts

{Object}

the visual effect options

Properties

Name	Type	Description
`effect`	{string}	the MochiKit.Visual effect name
`queue`	{string}	the MochiKit.Visual queue handling, defaults to "replace" and a unique scope for each widget (see `MochiKit.Visual` for full options)

Inherited From:

RapidContext.Widget#animate

Deprecated:

Use CSS animations instead.

Example:

widget.animate({ effect: "fade", duration: 0.5 });
widget.animate({ effect: "Move", transition: "spring", y: 300 });

Source:

RapidContext_Widget.js, line 492

blurAll()

Blurs (unfocuses) this DOM node and all relevant child nodes. This function will recursively blur all <a>, <button>, <input>, <textarea> and <select> child nodes found.

Inherited From:: RapidContext.Widget#blurAll
Source:: RapidContext_Widget.js, line 510

cancel()

Cancels the active page operation. This method will also reset the page status of the currently active page to ANY. This method is triggered when the user presses the "Cancel" button.

See:: RapidContext.Widget.Pane.ANY
Source:: RapidContext_Widget_Wizard.js, line 283

destroy()

The internal widget destructor function. This method should only be called by destroyWidget() and may be overridden by subclasses. By default this method does nothing.

Inherited From:: RapidContext.Widget#destroy
Source:: RapidContext_Widget.js, line 194

disable()

Disables this widget if it was previously enabled. This method is equivalent to calling setAttrs({ disabled: true }).

Inherited From:: RapidContext.Widget#disable
Source:: RapidContext_Widget.js, line 424

done()

Sends the wizard onclose signal. This method is triggered when the user presses the "Finish" button.

Source:: RapidContext_Widget_Wizard.js, line 315

enable()

Enables this widget if it was previously disabled. This is equivalent to calling setAttrs({ disabled: false }).

Inherited From:: RapidContext.Widget#enable
Source:: RapidContext_Widget.js, line 416

getChildNodes() → {Array}

Returns an array with all child pane widgets. Note that the array is a real JavaScript array, not a dynamic NodeList.

Returns:: {Array} the array of child wizard page widgets
Overrides:: RapidContext.Widget#getChildNodes
Source:: RapidContext_Widget_Wizard.js, line 126

hasClass(…cls) → {boolean}

Checks if this HTML DOM node has the specified CSS class names. Note that more than one CSS class name may be checked, in which case all must be present.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to check

Returns:

{boolean} true if all CSS classes were present, or false otherwise

Inherited From:

RapidContext.Widget#hasClass

Source:

RapidContext_Widget.js, line 315

hide()

Hides this widget node if it was previously visible. This method is equivalent to calling setAttrs({ hidden: true }). It is safe for all types of widgets, since it only adds the widgetHidden CSS class instead of setting the display style property.

Inherited From:: RapidContext.Widget#hide
Source:: RapidContext_Widget.js, line 470

isDisabled() → {boolean}

Checks if this widget is disabled. This method checks both the "widgetDisabled" CSS class and the disabled property. Changes to the disabled status can be made with enable(), disable() or setAttrs().

Returns:: {boolean} true if the widget is disabled, or false otherwise
Inherited From:: RapidContext.Widget#isDisabled
Source:: RapidContext_Widget.js, line 395

isHidden() → {boolean}

Checks if this widget node is hidden. This method checks for the existence of the widgetHidden CSS class. It does NOT check the actual widget visibility (the display style property set by animations for example).

Returns:: {boolean} true if the widget is hidden, or false otherwise
Inherited From:: RapidContext.Widget#isHidden
Source:: RapidContext_Widget.js, line 437

next()

Moves the wizard forward to the next page and sends the onchange signal. The page will not be changed if the active page fails a validation check. This method is triggered when the user presses the "Next" button.

Source:: RapidContext_Widget_Wizard.js, line 305

previous()

Moves the wizard backward to the previous page and sends the onchange signal. This method is triggered when the user presses the "Previous" button.

Source:: RapidContext_Widget_Wizard.js, line 294

removeAll()

Removes all children to this widget. This method will also destroy and child widgets and disconnect all signal listeners. This method uses the getChildNodes() and removeChildNode() methods to find and remove the individual child nodes.

Inherited From:: RapidContext.Widget#removeAll
Source:: RapidContext_Widget.js, line 582

removeChildNode(child)

Removes a single child DOM node from this widget. This method is sometimes overridden by child widgets in order to hide or control intermediate DOM nodes required by the widget.

Note that this method will NOT destroy the removed child widget, so care must be taken to ensure proper child widget destruction.

Parameters:

Name	Type	Description
`child`	{Widget\|Node}	the DOM node to remove

Inherited From:

RapidContext.Widget#removeChildNode

Source:

RapidContext_Widget.js, line 553

removeClass(…cls)

Removes the specified CSS class names from this HTML DOM node. Note that this method will not remove any class starting with "widget".

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to remove

Inherited From:

RapidContext.Widget#removeClass

Source:

RapidContext_Widget.js, line 353

setAttrs(attrs)

Updates the widget or HTML DOM node attributes. This method is sometimes overridden by individual widgets to allow modification of additional widget attributes.

Parameters:

Name Type Description

attrs

{Object}

the widget and node attributes to set

Properties

Name	Type	Attributes	Description
`disabled`	{boolean}	<optional>	the disabled widget flag
`hidden`	{boolean}	<optional>	the hidden widget flag
`class`	{string}	<optional>	the CSS class names

Inherited From:

RapidContext.Widget#setAttrs

Source:

RapidContext_Widget.js, line 246

setStyle(styles)

Updates the CSS styles of this HTML DOM node. This method is identical to MochiKit.Style.setStyle, but uses "this" as the first argument.

Parameters:

Name	Type	Description
`styles`	{Object}	an object with the styles to set

Inherited From:

RapidContext.Widget#setStyle

Example:

widget.setStyle({ "font-size": "bold", "color": "red" });

Source:

RapidContext_Widget.js, line 294

show()

Shows this widget node if it was previously hidden. This method is equivalent to calling setAttrs({ hidden: false }). It is safe for all types of widgets, since it only removes the widgetHidden CSS class instead of setting the display style property.

Inherited From:: RapidContext.Widget#show
Source:: RapidContext_Widget.js, line 460

toggleClass(…cls) → {boolean}

Toggles adding and removing the specified CSS class names to and from this HTML DOM node. If all the CSS classes are already set, they will be removed. Otherwise they will be added.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to remove

Returns:

{boolean} true if the CSS classes were added, or false otherwise

Inherited From:

RapidContext.Widget#toggleClass

Source:

RapidContext_Widget.js, line 376

uid() → {string}

Returns the unique identifier for this DOM node. If a node id has already been set, that id will be returned. Otherwise a new id will be generated and assigned to the widget DOM node.

Returns:: {string} the the unique DOM node identifier
Inherited From:: RapidContext.Widget#uid
Source:: RapidContext_Widget.js, line 182

Events

oncancel

Emitted when the user selects to cancel the page flow.

Source:: RapidContext_Widget_Wizard.js, line 106

onchange

Emitted when a page transition is performed.

Source:: RapidContext_Widget_Wizard.js, line 99

onclose

Emitted when the user has completed the page flow.

Source:: RapidContext_Widget_Wizard.js, line 113