Using JSDialog and API

The most used classes and methods:

JSDialog class

This is the mail class of the library. It is used for showing messages, configrmation dialogs and creating custom windows.

JSDialog.instances: Array of JSDialog.DialogInstance
This array contains a list of created dialogs and can be used in debugging purposes. Do not change it manually.
JSDialog.showMessageDialog(text [, icon, func, width, height, title, buttonTitle])
Creates and shows the message or alert. Use this function to show the dialog with the only button ("OK" by default) and message inside it. All parameters except text are optional. Example of use:
JSDialog.showMessageDialog("Hello, World!");
or:
JSDialog.showMessageDialog(
    "This was a big mistake", 
    "error", 
    function() { console.log('Closed'); }
);
Message dialog screenshot See more samples and demos of message dialog usage.
text: String
Default value: no (required)
The text message for the dialog. Please specify plain text here. All HTML tags will be encoded. Use standard line delimiter \n to specify multiline message.
type: String
Default value: "info"
Available values: "info", "warning", "error", "confirm", "none", or any custom URL
The type of the message. This parameter affects to the icon displayed in the dialog and its default title. If none value is set then "Information" title will be used by default. If this value contains an URL it will be used to display custom icon placed on this URL (with "Information" title by default). We recommend you to use 64x64px icons.
func: function()
Default value: null
The function which is called on the dialog is closed.
width: Integer
Default value: 450
The width for the new dialog in pixels. This is the width of content area only, the borders depends of the used skin and will be added to this width automatically.
height: Integer
Default value: 84
The height for the new dialog in pixels. This is the height of content area only, the borders and height of title and buttons depends of the used skin and will be added to this height automatically.
title: String
Default value: depends of type
By default the title is got by type value. This option lets you set your own title.
buttonTitle: String
Default value: "OK"
Set this option to override default button name.
JSDialog.showConfirmDialog(text, func, type, buttons, width, height, title)
Creates and shows the confirmation dialog. Text, buttons, handler and other parameters can be customized. Usage sample:
JSDialog.showConfirmDialog(
    "Do you want to continue?",
    function(result) {
        if (result == 'ok')
            console.log("User confirmes the operation"); 
    }
);
or:
JSDialog.showConfirmDialog(
    "Are you sure?\nAll unsaved changes will be lost",
    function(result) {
        if (result == 'ok')
            console.log("Yes pressed"); 
    },
    "warning",
    "yes:Yes, sure!|no|abort"
);
Confirmation dialog See more samples and demos of confirmation dialog usage.
text: String
The text message for the dialog. Please specify plain text here. All HTML tags will be encoded. Use standard line delimiter \n to specify multiline message.
type: String
Default value: "info"
Available values: "info", "warning", "error", "confirm", "none", or any custom URL
The type of the message. This parameter affects to the icon displayed in the dialog and its default title. If none value is set then "Information" title will be used by default. If this value contains an URL it will be used to display custom icon placed on this URL (with "Information" title by default). We recommend you to use 64x64px icons.
buttons: String
Default value: "ok|cancel"
Definition of buttons set and (optionally) their titles. Format: button1[:title1]|button2[:title2]... You can do not set titles in this case default titles for specifiend buttons will be used. The list of buttons available: yes (synonyms with other titles: ok, confirm, accept no (synonyms with other titles: decline) cancel (synonyms with other titles: abort) Note that using synonyms of the buttons will not affect to return result in the function func passed as the handler.
width: Integer
Default value: 450
The width for the new dialog in pixels. This is the width of content area only, the borders depends of the used skin and will be added to this width automatically.
height: Integer
Default value: 84
The height for the new dialog in pixels. This is the height of content area only, the borders and height of title and buttons depends of the used skin and will be added to this height automatically.
title: String
Default value: depends of type
By default the title is got by type value. This option lets you set your own title.
Creates and returnes new dialog instance. This is the main function of the library.
Please use it to create any dialogs except message and confirmation dialogs.
parameters is associative array containing all options for new dialog.
Sample usage:
JSDialog.create(
    {
        elementId: 'btnId',
        title: 'My custom dialog',
        contents: '<p>My custom text</p>',
        onOk: function() { console.log('OK'); }
    }
);  
Custom dialog See more samples and demos of custom dialog usage.

JSDialog.DialogDefinition class

This is associative array to pass inside JSDialog.create function. See its sample usage to see how you can set this array.

Full list of parameters keys:

element: DOM element
Default value: null
(optional) Element on the page dialog is to be called by pressing on. Use this parameter to specify a button element which calls your dialog (on onclick event).
elementId: String
Default value: null
(optional) ID of the element which will call the dialog on the onclick event. The save as element parameter but DOM element will be found by ID not by direct linking to it. API
elementClass: String
Default value: null
(optional) The same like elementId but the search is made by class name. The first found element with specified class will open the dialog on its onclick event.
title: String
Default value: ""
The title for new dialog
width: Integer
Default value: 400
The width for the new dialog in pixels. This is the width of content area only, the borders depends of the used skin and will be added to this width automatically.
height: Integer
Default value: 300
The height for the new dialog in pixels. This is the height of content area only, the borders and height of title and buttons depends of the used skin and will be added to this height automatically.
autoCenter: Boolean
Default value: true
Available values: true, false
false will disable dialog centering on show and on size change events
contents: String
Default value: ""
HTML contents of the dialog
buttons: Array of definitions for JSDialog.ButtonDefinition
Default value: []
The array of parameters for creating Buttons. All buttons will be created in the same order they are placed into array.
hasCloseBtn: Boolean
Default value: true
Available values: true, false
The close button is "x" button in the title of the dialog. onCancel event is attached to this button. Set this option to false to hide it.
onShow: function(JSDialog.DialogInstance)
Default value: null
This event handler is called on each dialog show.
onFirstShow: function(JSDialog.DialogInstance)
Default value: null
Use this event handler to apply some changes to the dialog on first show.
onHide: function(JSDialog.DialogInstance)
Default value: null
Called each time the dialog is being hidded, regardless of what button (OK, Cancel, etc.) was the initiator of dialog closing. This function is called after possible onOk or onCancel call.
onCancel: function(JSDialog.DialogInstance)
Default value: null
Called before dialog is to be closed by clicking "Cancel" button or "x" button in the title. This function must return true to allow closing the dialog or false to disallow it. If this hook is not defined, dialog assumes that closing is always allowed without any conditions.
onOk: function(JSDialog.DialogInstance)
Default value: null
Called before dialog is to be closed by clicking "OK" button.

JSDialog.DialogInstance class

This is the class for all runtime-generated dialogs. When you create any dialog object you get this class instance as result. Use is to manipulate created dialog.

elDlg: DOM element
The link to DOM element with root element for current dialog
elContent: DOM element
An element which is used to store all dialog contents. This element is inside elDlg element.
elBg: DOM element
An element for background of the dialog placed outside elDlg element. Note that this element may be null if background feature is disabled by your configuration.
function destroy()
Hides dialog and removes link from JSDialog.instances array.
function show()
Show the dialog.
function hide()
Hides the dialog.
function center()
Centers the dialog inside the browser. If you use autocenter option (by default) you do not need to call this method manually.
function setTitle(title)
Sets the title of the dialog.
function setSize(width, height)
Sets the width and height of the content area of the dialog (except borders). If autocenter option is enabled, window is centered then.
function setWidth(width)
Sets the width of the content area of the dialog (except borders). If autocenter option is enabled, window is centered then.
function setHeight(height)
Sets the height of the content area of the dialog (except borders). If autocenter option is enabled, window is centered then.
function getWidth(): integer
Returnes width of the content area of the dialog.
function getHeight(): integer
Returnes height of the content area of the dialog.
function getWidthWithBorders(): integer
Returns width of content area of the dialog + width of its borders.
function getHeightWithBorders()
Returns height of content area of the dialog + height of its borders + height of buttons area (if any button).
function getLeft(): integer
Returnes left position of the dialog.
function getTop(): integer
Returnes top position of the dialog.
function getHorizontalBorders(): integer
Returnes the width of horizontal borders of the dialog.
function getVerticalBorders(): integer
Returnes the width of vertical borders of the dialog.
function hasButtons(): boolean
Retunes is there any buttons were placed on this dialog.
function getButton(buttonName): JSDialog.ButtonInstance
Returnes button instance with specified name.
function getOkButton(): JSDialog.Button
Alias for getButton function returning "OK" button.
function getCancelButton(): JSDialog.Button
Alias for getButton function returning "Cancel" button.
function getCloseButton(): JSDialog.Button
Alias for getButton function returning "x" button (close button in the title of the dialog).
function getZIndex()
Returnes zIndex of current dialog.
function setZIndex(zIndex)
Sets zIndex for current dialog. Do not use this function if you do not fully understand why you need it. Wherever is possible please define zIndex of the dialogs in the global config: JSDialog.Config.

JSDialog.ButtonDefinition

This is the associative array for defining the button inside JSDialog.create function.

It has these parameters:

name: String
Optional for accessing the button
type: String
Default value: "custom"
Available values: "ok", "cancel", "custom"
The type of the button. OK and Cancel buttons will try to close dialog on click (they will call onOk and onCancel functions). Custom buttons do not have any default behaviour.
title: String
Default value: Depends of type
The title for the button. If you use "ok" or "cancel" type for this button you may not define this value.
func: function(dlg: JSDialog.DialogInstance)
Default value: null
Optional onClick handler. For OK and Cancel buttons dialog will be closed if this function returns true
enabled: boolean
Default value: true
Available values: true, false
Default enabled state for the button

JSDialog.ButtonInstance class

The class representing button object on a dialog.

You do not need to create this object manually, but you may need to know its API for changing buttons in runtime. For example you can call this code to disable your "OK" button::

dlgInstance.getOkButton().setEnabled(false);
function setTitle(title)
Set the title of the button
function setEnabled(isEnabled)
Changes enabled state of the button

JSDialog.Config class

This global class is used to preconfigure the JSDialog. Use it before creating any dialogs to set visual theme, change CSS and HTML templates of the dialogs.

JSDialog.Config.loadSkin()
By default JSDialog used lazy styles load. It will attach CSS to the document only after first dialog will be created. You can change this behaviour by using loadSkin method.
JSDialog.Config.unloadSkin()
Unloads skin (CSS) from the JSDialog. You can clean up your current skin before setting a new one.
JSDialog.Config.skin: String
Default value: default
The skin (visual) for all dialogs. See root folder of JSDialog to see the list of available skins (including the custom ones if you have created them).
JSDialog.Config.zIndexStart: integer
Default value: 11010
Starting zIndex for placing dialogs into the document. Change this value if elements of your web application are higher than default zIndex of JSDialog.
JSDialog.Config.templateDialog: String (HTML)
To redefine dialogs visual style use padding another HTML template into this parameter before creading any of dialogs. By default JSDialog uses this template (change it as you want):
<div class="jsdialog_dlg">
    <div class="jsdialog_title">
        <div class="jsdialog_title_text"></div>
        <div class="jsdialog_x">×</div>
    </div>
    <div class="jsdialog_content_wrap">
        <div class="jsdialog_content"></div>
    </div>
    <div class="jsdialog_buttons"></div>
</div>
JSDialog.Config.templateButton: String (HTML)
If you are creating a new skin, you might wand to set and buttons template to. By default the button is simple tag "a" styled with CSS only, you can change it. The only to remember is that JSDialog will use exactly root tag of buttons to insert styles and text content inside it. By default it's equals:
<a></a>
JSDialog.Config.templateBg: String (HTML)
The template for rendering background of the dialog. In ohter words it is the tag which by default is displayed behind the dialog and shadows currently inactive document. Without this tag (even with a little opacity) all elements behind the dialog will be available to interact with. Default code for it:
<div class="jsdialog_bg"></div>
JSDialog.Config.contentBorders: Array[top, right, bottom, left, buttonsHeight]
Default value: [45, 10, 10, 10, 60]
The array with 5 integer elements which define width and heigth of borders of dialogs and the height of buttons panel. This values are needed in dynamic way so there is no possibility to set them in CSS only. Please specify this value if you are creating another skin with different to default borders.
JSDialog.Config.css: String (URL)
Default value: Depends to JSDialog.skin
No default CSS will be used if you set custom URL for this option. By default JSDialog loads skin/jsdialog.css from its root folder.
JSDialog.Config.useCss: Boolean
Default value: true
Available values: true, false
If you change this value to false no default skin-related CSS will be embedded to the document at all. Be sure that you include it in the document in other way instead of default mechanism.

JSDialog.Lang class

This class contains all string used by JSDialog. Use it to localize JSDialog library to other language. Localizing must be done before any dialogs are created. For example:

JSDialog.Lang = {
    ok: "OK",
    yes: "Да",
    confirm: "Подтвердить",
    ...
};

The list of keys in JSDialog.Lang object:

ok"OK"
yes"Yes"
confirm"Confirm"
accept"Accept"
no"No"
decline"Decline"
cancel"Cancel"
abort"Abort"
information"Information"
warning"Warning"
error"Error"
confirmation"Confirmation"