• Initialization
• Templates
• Showing a dialog
• Dialog Positions
• Supported Input Types
• Dialog Titles

• Templates
• Showing a Dialog
• Dialog Positions
• Supported Input Types
• Dialog Titles
• Custom Button Labels
• Custom Buttons
• Lifecycle Callbacks
• Closing via Enter key
• CSS Classes

Dialogs

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

jsPlumbToolkit.Dialogs.initialize({
  selector:".dlg"
});

..or with a map of dialog id -> details:

jsPlumbToolkit.Dialogs.initialize({
  dialogs:{
    "editor":[ "<div class=\"editor\">FOO</div>", "Editor", false ]
  }
});

The three arguments in the array are [ content, title, isCancelable ]. title and 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.

TOP

Each dialog has a template in the HTML, with some class name that you matched in the selector argument to the initialize call above:

<script type="jtk" class="dlg" id="dlgViewQuery" title="Edit Query">
  <textarea class="txtViewQuery" jtk-focus jtk-att="query">${query}</textarea>
</script>

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.

Binding Parameters

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

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.

TOP

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 onOK callback.

View Node

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.

jsPlumb.on(document, "tap", ".view .edit i", function () {
  var info = renderer.getObjectInfo(this);
  jsPlumbToolkit.Dialogs.show({
    id:"dlgViewQuery",
    data:info.obj.data,
    onOK:function(data) {
      // update data
      toolkit.updateNode(info.obj, data);
    }
  });
});

Dialog

onOK Callback

The 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:

{
  query:"the contents of the text area"
}

TOP

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:

jsPlumbToolkit.Dialogs.show({
  id:"dlgViewQuery",
  data:info.obj.data
  position:"bottom"
});

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.

TOP

The list of supported input types is:

• text
• radio button(s)
• checkbox
• select
• textarea

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 show call.

TOP

Custom Button Labels

The default button labels are "OK" and "Cancel". This can be overridden with the labels parameter on a show method call:

jsPlumbToolkit.Dialogs.show({
  id:"dlgViewQuery",
  data:info.obj.data
  position:"bottom",
  labels:{
    ok:"Yes",
    cancel:"No"
  }
});

TOP

Custom Buttons

You can provide your own buttons for use in a dialog, eg:

jsPlumbToolkit.Dialogs.show({
    id:"dlgFoo",
    buttons:[ button1, button2 ]
});

where button1 and 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-commit and 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 - jtk-clear-all:

var button3 = document.createElement("button");
button3.innerHTML = "CLEAR";
button3.setAttribute("jtk-clear-all", "true");
button3.className = "yourButtonClass clearButton";

jsPlumbToolkit.Dialogs.show({
    id:"dlgFoo",
    buttons:[ button3, button1, button2]
});

TOP

Lifecycle Callbacks

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:

• onOpen
• onOK
• onCancel
• onClose

You provide these in a globals argument to the initialize method:

jsPlumbToolkit.Dialogs.initialize({
  selector:".myDialog",
  globals:{
    onOpen:function() {
      console.log("a dialog was opened");
    },
    onClose:function() {
      console.log("a dialog was closed.");
    }
  }
});

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:

<script type="jtk" class="dlg" id="dlgViewQuery" title="Edit Query">
  <input type="text" class="txtViewQuery" jtk-focus jtk-att="query" jtk-commit="true"></input>
</script>

Textarea Elements

For textarea elements you can also use the jtk-commit attribute, but in this case you need to press ctrl+enter to close the dialog.

<script type="jtk" class="dlg" id="dlgViewQuery" title="Edit Query">
    <textarea class="txtViewQuery" jtk-focus jtk-att="query" jtk-commit="true"></textarea>
</script>

CSS Classes

This is the full list of classes used by the dialog code. There are defaults for these declared in jsplumbtoolkit-defaults.css.

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.