- Showing a Dialog
- Dialog Positions
- Supported Input Types
- Dialog Titles
- Custom Button Labels
- Custom Buttons
- Lifecycle Callbacks
- Closing via Enter key
- CSS Classes
Basic support for dialogs forms part of the Toolkit core. These dialogs provide a simple abstraction around the business of getting input from the user and dealing with it. They're not necessarily fully-featured enough for all applications - they were built for the demo pages in the Toolkit - but they do provide a reasonable amount of functionality for very little effort.
Note that currently (version 2.0.4) the Dialogs are included in the
jsplumbtoolkit.js file and
jsplumbtoolkit.tgz package, but they will be moved to a separate package in an upcoming release.
This page provides a discussion of the functionality offered, using the Database Visualizer application for reference.
To initialize the dialogs, first call
jsPlumbToolkit.Dialogs.initialize, either with an appropriate selector for the templates for your dialogs (see below for an explanation of this):
..or with a map of dialog id -> details:
The three arguments in the array are
[ content, title, isCancelable ].
isCancelable may be null; if
title is null an empty String is used, if
isCancelable is null it is assumed the dialog is cancelable.
isCancelable, if provided, should be provided as a Boolean and not as a String.
Each dialog has a template in the HTML, with some class name that you matched in the
selector argument to the
initialize call above:
In fact it doesn't necessarily need to be a class name that identifies your dialog templates - any valid selector will work. The code uses
document.querySelectorAll to retrieve matching elements.
These templates use the same template engine as the Surface renderer, so in this example you can see we've extracted
query from a View node's data, and injected it into the
textarea. But what might not be immediately obvious is the purpose of the
jtk-att attribute: it tells the dialog code that the value of this textarea should be passed to the OK handler, using the key
Note also in the above example, the
jtk-focus attribute: this tells the dialog handler that the textarea should be given the focus when the dialog first opens.
This example is the dialog that is shown when you edit a View query in the Database Visualizer. We provide the id of the template to use for the dialog, and we provide the View node's data as the backing data for the dialog. Then we provide an
Dialog Opening Code
We register a
tap listener on the pencil icon in the upper right corner and then inside the event handler we find the Toolkit object related to the clicked icon, then open a dialog to edit it.
data argument to the
onOK callback consists of an object whose key value pairs are determined by the
jtk-att attributes found in the template. Recall that above we had a textarea with
jtk-att:"query". This means that the
data argument to
onOK looks like this:
Dialogs may be positioned in one of four locations: top, bottom, left or right. In each location the dialog is centered in the other axis, eg. for
top, the dialog is positioned at the top of the viewport and centered in the X axis.
The default position is
top. You can provide a
position parameter to the
show method to specify a different location:
The vast majority of the positioning of these dialogs is controlled through the CSS in
jsplumbtoolkit-defaults.css. The only exception is the code that keeps the dialog centered in the minor axis when the viewport is resized. CSS is discussed below.
The list of supported input types is:
- radio button(s)
If you set a
title attribute on a dialog's template, that value will be used for the title of the dialog. Alternatively, you can provide a
title parameter to the
Custom Button Labels
The default button labels are "OK" and "Cancel". This can be overridden with the
labels parameter on a
show method call:
You can provide your own buttons for use in a dialog, eg:
button2 are DOM elements that each have a specific attribute set on them to indicate their function:
var button1 = document.createElement("button"); button1.innerHTML = "YES"; button1.setAttribute("jtk-commit", "true"); button1.className = "yourButtonClass"; var button2 = document.createElement("button"); button2.innerHTML = "NO"; button2.setAttribute("jtk-cancel", "true"); button2.className = "yourButtonClass";
The key things here are the
jtk-cancel attributes. When present, and set to
"true", the indicate the purpose of the button. Of course you can put anything you like in the array of
buttons; they do not need to have
jtk-** attributes set on them, and they do not even need to be
button DOM elements.
The contents of
buttons will have been added to the dialog prior to the
onOpen callback being called, so you can attach functionality to them inside there.
Custom clear button
There's one other attribute supported on custom buttons -
There are five lifecycle callbacks supported:
- onOpen Called when the dialog has been opened. The related DOM element for the dialog is passed to this method.
- onMaybeClose Called prior to
onOK, with the same data that will be passed to
onOK. If you return false from this, the dialog stays open.
- onOK Called when the user presses OK. The callback is provided a data object as discussed above.
- onCancel Called when the user presses cancel. No arguments are provided to the callback.
- onClose Called when dialog has been closed, regardless of how it was closed. No arguments are provided to the callback.
Global Lifecycle Callbacks
In addition to providing callbacks to each
show call, you can register a callback for each of these four events that will be called for every dialog show:
You provide these in a
globals argument to the
Closing via Enter key
Text Input Elements
You can set the
jtk-commit attribute on any text
input elements that you'd like to have close (and persist) the dialog when the user presses the enter key:
textarea elements you can also use the
jtk-commit attribute, but in this case you need to press ctrl+enter to close the dialog.
This is the full list of classes used by the dialog code. There are defaults for these declared in jsplumbtoolkit-defaults.css.
|jtk-dialog-underlay||The element that acts as the modal "mask"|
|jtk-dialog-overlay||The element that acts as the parent for dialog content|
|jtk-dialog-overlay-visible||Assigned to an overlay when the dialog is visible|
|jtk-dialog-overlay-x||Assigned to dialogs appearing in the `top` or `bottom` positions.|
|jtk-dialog-overlay-y||Assigned to dialogs appearing in the `left` or `right` positions.|
|jtk-dialog-overlay-top||Assigned to dialogs appearing in the `top` position|
|jtk-dialog-overlay-bottom||Assigned to dialogs appearing in the `bottom` position|
|jtk-dialog-overlay-left||Assigned to dialogs appearing in the `left` position|
|jtk-dialog-overlay-right||Assigned to dialogs appearing in the `right` position.|
|jtk-dialog-buttons||Button container element|
|jtk-dialog-button||An individual button in a dialog|
|jtk-dialog-title||The titlebar of a dialog|
|jtk-dialog-content||The content of a dialog (does not contain the titlebar)|
The default CSS stylesheet also contains several rules such as hover states etc. You may wish to keep that in mind when you write your app-specific overrides.