User Guide

Overview

The wijdialog widget extends jquery.ui.dialog and adds maximizing, minimizing, content toggling and pinning features for jquery.ui.dialog.

The image below illustrates the main elements of the wijdialog widget:

NOTE: This documentation pertains to the latest Wijmo release. Please check the Version Histories for an outline of new features, improvements, and changes to the Wijmo widgets.

Markup and Scripting

The following markup can be used to create the HTML element that will become the widget as well as the dialog's content:

<div>                 
<input type="button" value="Hide Dialog" onclick="$('#dialog').wijdialog('close')" />                 
<input type="button" value="Show Dialog" onclick="$('#dialog').wijdialog('open')" />                 
<div id="dialog" title="Basic dialog">       
</div>             
</div> 

The majority of the time, you'll want the wijdialog to show up during an event, such as an onClick event. For example, the above markup includes markup to create buttons that will show or hide the wijdialog widget.

The following script initializes the widget:

<script id="scriptInit" type="text/javascript">
      $(document).ready(function () {
          $('#dialog').wijdialog({
                   autoOpen: false,
                  captionButtons: {
                  refresh: { visible: false}
              }
          });
      });    
   </script>

The markup and script featured here results in the following:

Quick Start

In this quick start, you will learn how to add the Dialog widget to an HTML project and how to customize the widget.

1. Create an .html page and add links to the dependencies to your project. To do this, just link to the content delivery network (CDN) file for each project:

   <!--jQuery References-->
   <script src="http://code.jquery.com/jquery-1.9.1.min.js" type="text/javascript"></script>
   <script src="http://code.jquery.com/ui/1.10.1/jquery-ui.min.js" type="text/javascript"></script>
    
   <!--Theme-->
   <link href="http://cdn.wijmo.com/themes/aristo/jquery-wijmo.css" rel="stylesheet" type="text/css" />
    
   <!--Wijmo Widgets CSS-->
   <link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css" rel="stylesheet" type="text/css" />
    
   <!--Wijmo Widgets JavaScript-->
   <script src="http://cdn.wijmo.com/jquery.wijmo-open.all.3.20131.1.min.js" type="text/javascript"></script>
   <script src="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.js" type="text/javascript"></script>
   

   You can reference the latest dependencies from the CDN at http://wijmo.com/downloads/#wijmo-cdn.

2. Place the following markup within the body of the .html document:

   <div id="dialog" title="Basic dialog">       
   </div>  
   

3. To initialize the widget, you need to add some jQuery script.

   <script id="scriptInit" type="text/javascript">
         $(document).ready(function () {
             $('#dialog').wijdialog({
                 autoOpen: true,
                 captionButtons: {
                     refresh: { visible: false}
                 }
             });
         });    
      </script>

4. If you run your application now, the wijbarchart will resemble the following image:



Changing the wijdialog's Appearance

You can always use jQuery's Themeroller to roll your own theme, but you can also use CSS styling to quickly change a few aspects of the wijdialog's appearance. You can find a list of the available CSS selectors in the C1Dialog CSS Selectors topic.

1. Add the following tag set after the jQuery script:

   <style type="text/css">
   
   </style>
   

2. Insert the following script between the <style> tags to add CSS styling to your control.

   <style type="text/css">
          .wijmo-wijdialog 
               {
                   color: #0088FF; 
                   background: #9933FF; 
                   border-color: #000000; 
                   border-width: thick; 
                   font-family: BlackadderITC; 
                   font-size: large; 
               }
               .wijmo-wijdialog-captionbutton
               {
                   background: #1892BA;
               }
      </style>
   

3. If you run your application, your dialog widget should resemble the following image.



API

Options

The following options are included in the ComponentOne wijdialog widget:

autoOpen

The autoOpen option allows the dialog to open automatically when the dialog is called if it is set to true.

Type: Boolean

Default: true

Code Example:

In general, you'll set the option like this:

$("selector").wijdialog({autoOpen: false});

Here's a sample that shows the autoOpen option in context:

$('#dialog').wijdialog({
	autoOpen: true
   });

buttons

The buttons option specifies the buttons that will be displayed within the dialog content area. The property key is the button text. The value is the callback function when the button is clicked. The context of the callback is the dialog element. Access to the button is available as the target of the event object.

Type: Object,

Default: {}

Code Example:

Here's the general way you'll set the option:

$("selector").wijdialog({buttons: {ok: function(){…}});

Here's a sample that shows the buttons option in context. This sample is from the Alert Dialog demo:

buttons: {
       Ok: function () {
            $(this).wijdialog("close");
          }
     }, 

You can see the button that you created with the buttons option in the following image:



buttons

The buttons option specifies which buttons will be displayed within the dialog content area. Each element of the array must be an Object defining the button properties.

Type: Array

Default: []

Code Example:

Here's the general way you'll set the option:

$("selector").wijdialog({buttons: [{text:"ok", click: function(){…}}]);

Here's a more specific sample that will allow you to create an "ok" button that causes the dialog to close when it's clicked.

$('#dialog').wijdialog({
    autoOpen: true,
	buttons: [{
		text: "ok",
		click: function() {
		      $(this).wijdialog("close");
		   }
	 }]

captionButtons

The captionButtons option allows you to specify the caption buttons that will be shown on the wijdialog title bar. By default, all of the buttons are visible. You can customize the caption buttons' icons by using the jQuery UI Framework Icons.

Type: Object

captionButtons and Default values:

close

The close button will close the wijdialog widget.

close: {visible: true, click: self.close, iconClassOn: 'ui-icon-close'}

maximize

The maximize button enlarges the wijdialog widget to fill the screen.

maximize: {visible: true, click: self.maximize, iconClassOn: 'ui-icon-extlink'}

minimize

The minimize button shrinks the wijdialog widget to a task bar at the bottom of the screen.

minimize: {visible: true, click: self.minimize, iconClassOn: 'ui-icon-minus'}

pin

The pin button allows the user to pin the wijdialog widget so it can't be moved. When the dialog is pinned, the button will look like this:

pin: {visible: true, click: self.pin, iconClassOn: 'ui-icon-pin-w', iconClassOff:'ui-icon-pin-s'}

refresh

The refresh button refreshes the wijdialog widget content.

refresh: {visible: true, click: self.refresh, iconClassOn: 'ui-icon-refresh'}

toggle

The toggle button expands or collapses the wijdialog widget's content area. When you've collapsed the dialog's content area, the toggle button will resemble the following image:

toggle: {visible: true, click: self.toggle, iconClassOn: 'ui-icon-carat-1-n', iconClassOff:'ui-icon-carat-1-s'}

captionButton Properties

You can set the following properties for each captionButton:

click

click is the event handler for the button's click event.

iconClassOff

This option defines the button icon after clicking.

iconClassOn

This option defines the button icon in its normal state.

visible

This object specifies the button's visibility.

Code Example:

In this example, you can see some of the captionButtons' settings:

captionButtons: {
			  pin: { visible: true, iconClassOn: 'ui-icon-heart', iconClassOff: 'ui-icon-home' },
			  refresh: { visible: true, iconClassOn: 'ui-icon-print', iconClassOff: 'ui-icon-check' },
			  toggle: { visible: true, iconClassOn: 'ui-icon-carat-1-n', iconClassOff: 'ui-icon-wrench' },
			  minimize: { visible: true, iconClassOn: 'ui-icon-minusthick', iconClassOff: 'ui-icon-gear' },
			  maximize: { visible: true, iconClassOn: 'ui-icon-circle-arrow-n', iconClassOff: 'ui-icon-cart' }
				}

The sample above creates caption buttons that resemble those in the following image. The caption buttons icons are from the jQuery UI Framework Icons:



closeOnEscape

The closeOnEscape option allows the user to close the dialog widget by pressing the escape (ESC) key when the widget has focus.

Type: Boolean,

Default: true

Code Example:

In general, this is how you'll set the closeOnEscape option:

$("selector").wijdialog({closeOnEscape: false});

Here's the closeOnEscape option in context:

$('#dialog').wijdialog({
	closeOnEscape: true
  });

closeText

The closeText option specifies the text for a close button. The close text is hidden when using a standard theme.

Type: String

Default: "close"

Code Example:

$("selector").wijdialog({closeText: "close"});

contentUrl

This option specifies the URL for the iframe element inside wijdialog. You can see this option in use in the External Content demo.

Type: String

Default:

Code Example:

Here's the general way you'll set the option:

$("selector").wijdialog({contentUrl: 'http://www.google.com'});

Here's the sample from the demo. When the dialog opens, it will display the wijmo homepage:

$("#dialog").wijdialog({ 
				width: 840, 
				height: 640, 
				contentUrl: 'http://www.wijmo.com', 
				autoOpen: true 
			});
        }); 

dialogClass

This option specifies the class name(s) that will be added to the dialog for additional theming.

Type: String,

Default: ""

Code Example:

$("selector").wijdialog({dialogClass: "alert"});

disabled

This option disables or enables the dialog. It can be set when initialising the dialog.

Type: Boolean

Default: false

Code Example:

Here's the general way you'll set the option:

$("selector").wijdialog({disabled: true});

Here's a sample that sets the disabled option to "true"

$(document).ready(function () {
          $('#dialog').wijdialog();
		  $('#dialog').wijdialog("option", "disabled", "true");
		});  

This is how the dialog appears when it is disabled. Note that the toggle button doesn't change state when the mouse hovers over it:



draggable

The draggable option allows the user to drag the widget by the titlebar. Since the default behavior is to allow dragging, set this option to "false" if you don't want users dragging the dialog to another position. This is how the dialog widget looks when you begin dragging:



Type: Boolean

Default: true

Code Example:

$("selector").wijdialog({draggable: false});

expandingAnimation

The expandingAnimation option determines the animation effect that is used when the wijdialog is expanded.

Type: Object

Default: null

effect

The animation effect you apply to the dialog. This animation effect will control how the dialog behaves as it expands. Please see the Animation Effects topic for a list of the available animation effects.

duration

The duration of the animation in milliseconds.

easing

A value that indicates the easing function that will be applied to the animation. For more information, please see the Easing topic.

Code Example:

$("#dialog").wijdialog({
        expandingAnimation: { 
               effect: "puff", 
               duration: 300, 
               easing: "easeOutExpo" 
        }
   });

height

The height option determines the height of the dialog in pixels. It can also be set to 'auto' which allows the dialog to adjust its height based on its content. Allowing the dialog to automatically adjust its height based on its content is especially useful when you're using it with the contentUrl option. You can see this option set in the source of the External Content demo.

Type: Number

Default: auto

Code Example:

$("selector").wijdialog({height: 600});

Here's the height option set to 'auto'

$('#dialog').wijdialog({
	height: auto
  });

hide

The hide option determines the animation effect to be used when the dialog is closed. For a list of the available animation options, please see the Animation Effects topic.

Type: String

Default: "slide"

Code Example:

$("selector").wijdialog({hide: "slide"});

maxHeight

The maxHeight option determines the maximum height to which the dialog can be resized, in pixels.

Type: Number

Default: false

Code Example:

$("selector").wijdialog({maxHeight: 400});

maxWidth

This option determines the maximum width to which the dialog can be resized, in pixels.

Type: Number

Default: false

Code Example:

$("selector").wijdialog({maxWidth: 300});

minHeight

The minHeight option determines the minimum height to which the dialog can be resized, in pixels.

Type: Number

Default: 150

Code Example:

$("selector").wijdialog({minHeight: 400});

minimizeZoneElementId

The minimizeZoneElementId option specifies the ID of the DOM element to dock to when wijdialog is minimized. This is especially useful if you wish to dock your dialog to a menu or to another element.

Type: String

Default:

Code Example:

$("selector").wijdialog({minimizeZoneElementId: "zoomId"});

minWidth

The minWidth option specifies the minimum width to which the dialog can be resized, in pixels.

Type: Number

Default: 150

Code Example:

$("selector").wijdialog({minWidth: 400});

modal

If the modal option is set to true, then when the dialog is opened other items on the page will be disabled. Modal dialogs create an overlay below the dialog but above other page elements. You can see the dialog widget with the modal overlay behind it in this image:



The image above uses the Rocket theme. Each theme will have a different modal overlay.

Type: Boolean

Default: false

Code Example:

$("selector").wijdialog({modal: true});

position

The position option determines where on a page the dialog widget will be displayed. The possible values are:

• a single string representing a position within the viewport: 'center', 'left', 'right', 'top', 'bottom'.
• an array containing an x,y coordinate pair in pixel offset from the left, top corner of the viewport (e.g. [350,100])
• an array containing x,y position string values (e.g. ['right','top'] for the top right corner).

Type: String, Array

Default: "center"

Code Example:

$("selector").wijdialog({position: "top"});

resizable

The resizable option allows you to control whether or not your users can resize the dialog. By default, resizable is set to "true" and allows users to change the size of the dialog. If you wish to block users from resizing the dialog, then set this option to "false." You can see the resize handle circled in the image below:



Type: Boolean

Default: true

Code Example:

$("selector").wijdialog({resizable: false});

show

The show option defines the animation effect to be used when the dialog is opened. For a list of the available animation options, please see the Animation Effects topic.

Type: String

Default: "slide"

Code Example:

$("selector").wijdialog({show: "fade"});

stack

The stack option allows the dialog to stack on top of other dialogs, causing it to move to the front of other dialogs when it gains focus.

Type: Boolean

Default: false

Code Example:

$("selector").wijdialog({stack: false});

title

The title option specifies what will appear in the dialog title bar. It may be any valid HTML markup or it may be specified by the title attribute on the dialog source element. You can see the title option set in the image below:



Type: String

Default: ""

Code Example:

Here's the general way you'll set the option:

$("selector").wijdialog({title: "Dialog Title"});

Here's the title option set in context:

 $('#dialog').wijdialog({
	title: "This is the new title!"
   });

width

An option that specifies the width of the dialog, in pixels. You can see this option set in the External Content demo source.

Type: Number

Default: 300

Code Example:

Here's the general way you'll set the option:

$("selector").wijdialog({width: 300});

Here's a sample from the External Content demo:

$("#dialog").wijdialog({ 
       width: 840, 
       height: 640,  
       contentUrl: 'http://www.wijmo.com', 
       autoOpen: true 
  }); 

zIndex

This option specifies the starting z-index for the dialog. This allows you to specify the starting stack order of the widget.

Type: Number

Default: 1000

Code Example:

$("selector").wijdialog({zIndex: 2000});

Events

The following events are included in the ComponentOne wijdialog widget:

beforeClose

The beforeClose event is called when the dialog attempts to close.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ close: function (e) { } });
//Bind to the event by type: wijdialogclose:
$(".selector").bind("wijdialogclose", function(e) { } );

blur

The blur event is called when the dialog widget loses focus.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

data.el: The DOM element of this dialog.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ blur: function (e, data) { } });
//Bind to the event by type: wijdialogblur:
$(".selector").bind("wijdialogblur", function(e, data) { } );

buttonCreating

The buttonCreating event is called before the caption buttons are created. It can be used to change the array of the buttons or to change, add, or remove buttons from the title bar.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

data: Buttons array that will be created.

Code Example:

//Supply a function as an option:
$("selector").wijdialog({ buttonCreating: function (e, data) { } });
//Bind to the event by type: wijdialogbuttoncreating:
$(".selector").bind("wijdialogbuttoncreating", function(e, data) { } );

close

The close event is called when the dialog is closed.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ close: function (e) { } });
//Bind to the event by type: wijdialogclose:
$(".selector").bind("wijdialogclose", function(e) { } );

create

The create event is called when the dialog is created.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ create: function (e) { } });
//Bind to the event by type: wijdialogcreate:
$(".selector").bind("wijdialogcreate", function(e) { } );

drag

The drag event is called when a user drags the dialog widget.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

data: related data

data,position: The position of wijdialog {top, left}.

data,offset: The offset of wijdialog {top, left}.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({drag: function (e, data) { } });
//Bind to the event by type: wijdialogdrag:
$(".selector").bind("wijdialogdrag", function(e, data) { } );

dragStart

The dragStart event is triggered when the user begins to drag the dialog widget.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

data: related data

data,position: The position of wijdialog {top, left}.

data,offset: The offset of wijdialog {top, left}.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({dragStart: function (e, data) { } });
//Bind to the event by type: wijdialogdragstart:
$(".selector").bind("wijdialogdragstart", function(e, data) { } );

dragStop

The dragStop event is triggered when the user stops dragging the dialog widget.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

data: related data

data,position: The position of wijdialog {top, left}.

data,offset: The offset of wijdialog {top, left}.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({dragStop: function (e, data) { } });
//Bind to the event by type: wijdialogdragstop:
$(".selector").bind("wijdialogdragstop", function(e, data) { } );

focus

The focus event is called when the wijdialog gains focus.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ focus: function (e) { } });
//Bind to the event by type: wijdialogfocus:
$(".selector").bind("wijdialogfocus", function(e) { } );

open

The open event is called when the dialog is opened.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ open: function (e) { } });
//Bind to the event by type: wijdialogopen:
$(".selector").bind("wijdialogopen", function(e) { } );

resize

The resize event is triggered when the user resizes the dialog widget.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

data: related data

data,originalPosition: the original position of wijdialog {top, left}.

data,originalSize: the original size of wijdialog {width, height}

data,position: the position of wijdialog {top, left}.

data,size: the size of wijdialog {width, height}

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ resize: function (e, data) { } });
//Bind to the event by type: wijdialogresize:
$(".selector").bind("wijdialogresize", function(e, data) { } );

resizeStart

The resizeStart event is triggered when the user begins to change the size of the dialog widget.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

data: related data

data,originalPosition: the original position of wijdialog {top, left}.

data,originalSize: the original size of wijdialog {width, height}

data,position: the position of wijdialog {top, left}.

data,size: the size of wijdialog {width, height}

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ resizeStart: function (e, data) { } });
//Bind to the event by type: wijdialogresizestart:
$(".selector").bind("wijdialogresizestart", function(e, data) { } );

resizeStop

The resizeStop event is triggered when the user finishes changing the size of the dialog widget.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

data: related data

data,originalPosition: the original position of wijdialog {top, left}.

data,originalSize: the original size of wijdialog {width, height}

data,position: the position of wijdialog {top, left}.

data,size: the size of wijdialog {width, height}

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ resizeStop: function (e, data) { } });
//Bind to the event by type: wijdialogresizestop:
$(".selector").bind("wijdialogresizestop", function(e, data) { } );

stateChanged

The stateChanged event is called when the dialog state ("maximized", "minimized", "normal") is changed.

Type: Function

Default: null

Parameters:

e: jQuery.Event object.

data.originalState: The original state of the dialog box.

data.state: The current state of the dialog box.

Code Example:

//Supply a function as an option:
$(".selector").wijdialog({ stateChanged: function (e, data) { } });
//Bind to the event by type: wijdialogstatechanged:
$(".selector").bind("wijdialogstatechanged", function(e, data) { } );

Methods

The following methods are included in the ComponentOne wijdialog widget:

close

The close method closes the dialog widget.

Code Example:

$("selector").wijdialog ("close");

destroy

The destroy method removes the wijdialog functionality completely and returns the element to its pre-init state.

Code Example:

$("selector").wijdialog ("destroy");

disable

The disable method disables the wijdialog.

Code Example:

$("selector").wijdialog ("disable");

enable

The enable method enables the wijdialog.

Code Example:

$("selector").wijdialog ("enable");

getState

The getState method gets the state of the dialog widget. Possible values are: minimized, maximized, and normal.

Code Example:

$('selector').wijdialog("getState");

isOpen

The isOpen method returns true if the wijdialog is currently open.

Code Example:

$("selector").wijdialog ("isOpen");

maximize

The maximize option maximizes the wijdialog.

Code Example:

$("selector").wijdialog("maximize");

minimize

The minimize method minimizes the wijdialog.

Code Example:

$("selector").wijdialog("minimize");

moveToTop

The moveToTop method moves the wijdialog to the top of the stack.

Code Example:

$("selector").wijdialog ("moveToTop");

open

The open method opens an instance of the wijdialog.

Code Example:

$("selector").wijdialog ("open");

option

The option method gets or sets any wijdialog option. If no value is specified, the method acts as a getter.

Parameters:

optionName (string) - The name of the option to set or get.

value (string) - The value to which to set the specified option.

Code Example:

$("selector").wijdialog ("option", optionName , value);

option

The option method sets multiple wijdialog options at once by providing an options object.

Parameter:

options (object) - The options to set.

Code Example:

$("selector").wijdialog ("option", options);

pin

The pin method prevents the wijdialog from being moved.

Code Example:

$("selector").wijdialog("pin");

refresh

The refresh method refreshes the iframe content within the wijdialog.

Code Example:

$("selector").wijdialog("refresh");

reset

The reset method resets dialog properties such as width and height to their default values.

Code Example:

$("selector").wijdialog("reset");

restore

The restore method restores the wijdialog to its normal size from either the minimized or the maximized state.

Code Example:

$("selector").wijdialog("restore");

toggle

The toggle method expands or collapses the content of the wijdialog.

Code Example:

$("selector").wijdialog("toggle");

widget

The widget method returns the .wijmo-wijdialog element.

Code Example:

$("selector").wijdialog ("widget");