Dialog:
Easy User Interactivity Anytime

Dialogs for offering user interaction are an essential element of Online Communication. Alas, standard HTML holds only very simple types of dialog. How you can easily equip your documents with even quite sophisticated dialogs, you can read in this article.

For a real application based on a Dialog  see my article
Involve the Users - Let Them "Customize" Your Document!
(there, in UserMenu click items  New int. Note ,  New ext. Note 
or, when the mouse is on a note,  Update Note )

If you want to include  user interactivity  to an online document, you are soon in a dilemma:

So I developed some Javascript functions for handling most of the user interactivity. To apply them in Online Communication, all you have to do are two steps:

  1. Develop an extra HMTL document representing the user interface (UIF) by which the users can enter their inputs. That's what's called a "Dialog".
  2. At designated places in the document call the dialog. To do so, in the dialog file  call the pre-coded functions
    • DialogCaller
    • DialogFooter
  3. DialogButtons
  4. Dialog
    		5.


This time in particular I would like to invite you: Please do spy on the source code! In view of the effort involved, you might sometimes wonder if a demo was really implemented as I said before, or if there was any trick at the bottom of it. To do that, you are explicitly asked to right-click anywhere on your browser and to click "View Source" in the context menu. (Don't forget to spy on both, this main window as well as the dialog window!)

































Preparing a Dialog

The most efficient way for preparing a dialog is the following:

  1. Consider which values you want to release for manipulation by the user. Note down their access code - identifier of a (global) variable, or a qualified identifier (e.g.  object.attribute ).
  2. Consider the representation form of each of the values. This dialog can handle values represented by a TEXTAREA , a  SELECT  or by selected standard HTML inputs (checkbox, file, password, radio buttons, text).
    All inputs are taken to be ASCII-strings.
  3. A feature that's new to user dialogs is  semi-modal  behavior:
    • Is your application such that it makes sense to the user if a dialog is offered only once, the user inputs are processed only after the user has closed the dialog?
      Then it should be a "modal" dialog (i.e. no  Blur  button in the dialog UIF).
    • Or is the dialog related to an operation that tends to be of an "iterative" nature, i.e. the user will probably need several dialogs to arrive at the desired result?
      Then it will be user-friendlier to let the user "blur" the dialog (= hide it in the task bar, to restore it later for the next iteration step). So the dialog should have a  Blur  button: when the user is clicking it, the input values are returned to the DialogCaller, the dialog window is minimized and hidden in the task bar.
  4. Design a layout for the dialog UIF (user interface):
    • Which input will be needed most frequently? It should be the first input in the UIF.
    • How should the other inputs be arranged to provide a very user-friendly dialog?
  5. The complete dialog is implemented by two separate HTML-files: Details you can find in the following two sub-sections.
































DialogCaller file

HTML-file from which the dialog is called. In its  <HEAD> … </HEAD>  part, or between the tags  </BODY>  and  </HTML> , include the following line:


<SCRIPT>DialogCaller([options])</SCRIPT>

Details about this function you can find in section DialogCaller()

For all the variables you want to pass to a dialog (= expose to user interaction), in the DialogCaller file there should be any of the following:

  1. any object attribute whose value is to be layed open to user interaction (see Direct Assignment)
  2. a  TEXTAREA 
  3. a  SELECT 
  4. selected standard HTML input types:
    • checkbox
    • file
    • hidden
    • password
    • radio
    • text
The access codes of these inputs will be listed in the first argument when calling the function Dialog()































Dialog file

  1. The framework of a dialog file is a normal HTML file. At its end, between the tags  </BODY>  and  </HTML> , include a special code line: <SCRIPT>DialogFooter()</SCRIPT>
    Details about this function you can find in section DialogFooter()
  2. The user inputs should be arranged in a table. The leftmost column could be a short prompt telling the users what the following input is about. The next column could be the respective input. Note that it should have an attribute  COLSPAN=x  ( x  being the dialog's maximum number of buttons: 2, 3 or 4). So the table would look like this: 
    <TABLE>
  <TR>
    <TD>(prompt)</TD>
    <TD COLSPAN="x"><TEXTAREA NAME="…" COLS="…" ROWS="…"></TEXTAREA>
    </TD>
  </TR>
  <TR>
    <TD>(prompt)</TD>
    <TD COLSPAN="x"><INPUT TYPE="…" NAME="…"></TD>
  </TR>
     :
</TABLE>
    Inputs of a group (TYPE= CHECKBOX  or  RADIO ) should all have the same  NAME .
    It might be a good idea to give to all input elements an attribute  ACCESSKEY="…"  Thus the users will be able to access them not only by clicking the mouse but also by pressing a key combination  ALT+…  on the keyboard.
  3. As the last row within the table provide the following coding: 
    <TR>
<TD></TD>
<SCRIPT>DialogButtons()</SCRIPT>
</TR>
    Details about this function you can find in section DialogButtons()
  4. If you think it's appropriate, you can provide a dialog help file:
    • Prepare any file  abc.xyz. The type  .xyz  can be any file format ( .htm ,  .txt  or any other file format - be it one that can be displayed by the browser, or by any other application).
    • When calling  Dialog(), include an option  help=abc.xyz  in its option string (= second argument). If the file name comprises whitespace, bracket it in single or double apostrophes (i.e.  help='abc.xyz'  or  help="abc.xyz" ).
  5. In the dialog file, if you want to do some pre-processing before the user inputs are returned to the DialogCaller, include options  func=xyz(arguments) ,  xyz  being the function you want to be executed before returning the user inputs.
    • At the top of the dialog file (typically between the  </HEAD>  tag and the  <BODY>  tag) code your preprocessing function, as usual for a Javascript function.
    • In function  DialogButtons()  include as the only argument a string representing the function call:
      <SCRIPT>DialogButtons("xyz(arguments)")</SCRIPT>
      Details about this function argument you can find in section DialogButtons() - Syntax
    That way you can, for example, have the user inputs checked for plausibility. If there seems to be something wrong with the user inputs, your function  xyz()  should return  false . If closing (or blurring) the dialog should proceed, that function should return  true . Thus you can keep the DialogCaller free of any doubtful user input, and you can process the inputs right away.
































Keyboard Inputs

Besides the usual keyboard handling of TEXTAREA and standard HTML inputs, in a semi-modal dialog there are some extra key strokes:

Ctrl + ENTER Pressing this key combination returns the current input values to the DialogCaller window and closes the dialog window. This behavior is suppressed if
  • function  DialogButtons()  was called with a custom function as its argument
  • this custom function returned  false 
    (details see section DialogButtons())
Ctrl + space Pressing this key combination "blurs" the dialog window:
  • the current input values are returned to the DialogCaller window
  • the dialog window is minimized, its icon appears in the task bar (from where the dialog can be restored at any time, when the user wants to do the next iteration step)
This behavior is suppressed if
  1. when the dialog was called, there was an option  noblur  (see  Dialog()  - Options)
  2. function  DialogButtons()  was called with a custom function as its argument  and this custom function returned  false  upon plausibility check (see section  function DialogButtons() )
ALT + ! If the dialog window has a help file of any browser-compatible type, it will be displayed in the same dialog window (replacing the dialog UIF). After reading, to return to the dialog, the users should press this key combination (i.e. you should remind them to do so).
Esc The dialog window is closed without returning input values to the DialogCaller window
































Hidden Inputs

Frequently you will want to have a variable offered in a dialog that is  internal  to the main window, i.e. it is not visible there.

Best would be, obviously, if the value entered by the user would be assigned to the variable directly. Unfortunately, that's not possible. Instead, you can provide an input of  TYPE="hidden" . This input is not visible to the user, though you can handle it just like any other input:

<INPUT TYPE="hidden" ID="id" [VALUE="start value"]>

In sub-section DialogCaller() - Options you will see how you can trigger your own function ("custom function") once fresh dialog return values are available. In that function you can access the user entry and assign it to the internal variable:

variable = id.value

It will be useful if that hidden input has an ID similar to the variable's identifier. Though you should watch out not to call it identically.

The part  VALUE="start value"  is optional. You will need it only if, in the dialog, you want some  start value  to be displayed in the respective input. The user can overwrite it  or  close/[blur] the dialog right away. In that case the  start value  will be assigned to the variable.

































Direct Assignment

Frequently you will want to prompt the user for an input whose value is to be assigned to any attribute of an object.

You could handle that, of course, in a somewhat complicated way: For each of them provide 'hidden' inputs in the main window, call the function  Dialog()  with an option  func=  referring to a Javascript function handling all the re-assignments of the input values returned from the dialog.

You can, however, also have the dialog assign them directly to the object's attributes.

To do that, simply give  qualified  names to the inputs in the dialog window (i.e. names comprising at least one '.'), reflecting where to assign them to. For example:

Let's assume, you have a link anchor in your main window to which you want to prompt the user for the destination and the label:

<A id="link" href="…destination…">label</A>

In the dialog window there should be two inputs with qualified names. Their types can be any of the types listed in section DialogCaller file (except, of course, the first one, an object's attributes).

Destination: <INPUT NAME="link.href" … >
Label: <INPUT NAME="link.innerText" … >

In the main window you need no extra provisions.

When the user blurs or closes the dialog, these input values will be assigned directly to the respective attributes.

One Thing that might cause Confusion:

One input character is not reflected in a note's contents: the  line break .
The reason is that the text entered by the user in the TEXTAREA of the dialog is interpreted not as text but as HTML. In HTML a line break is ignored and replaced by a space. So, tell the users that where they want to see a line break in the note, they should code it as  <BR> .

As well, a number of consecutive spaces in the TEXTAREA of the dialog is reduced to one space only.































function  DialogCaller()

This function is needed to handle the liaison with the dialog file: checking periodically for fresh return values, and closing it if the dialog window is still open when the DialogCaller window is about to close.

For its syntax, the place where to call it, and its options see the following sub-sections.

































DialogCaller() - Syntax

DialogCaller([options])

 options  is a string of keyword options, separated by blank space. A keyword option is of the form  keyword=value  If the  value  comprises blank spaces it should be bracketed in single or double quotes ( keyword='value'  or  keyword="value" ), depending on the context.

If no options are needed, the function should be called with an empty arguments list:  DialogCaller() 

For a table of the options currently available see sub-section DialogCaller() - Options.

































DialogCaller() - Where to Implement

Function  DialogCaller()  can be called anywhere before or after the  <BODY> … </BODY>  part of the DialogCaller file.

































DialogCaller() - Options

Currently the following options are available:

time Time interval for checking for return values, in milliseconds. By default, every 500 milliseconds will be checked if the dialog window has returned values. This timing will be enough for most applications, while still not overburdening the user's computer. Only in very time-critical applications you will want the DialogCaller window to respond faster.
func In many applications you will have a custom function for processing the value(s) returned by the dialog. By this option you can have it triggered once fresh return values are available. Just set this option to the code by which your custom function is to be called, i.e.
func=YourFunction([arguments])
If the arguments list comprises blank space, it should be bracketed in single or double quotes ( func='YourFunction(arg1 arg2 … )'  or  func="YourFunction(arg1 arg2 … )" ), depending on the context.
































function  DialogFooter()

This function is needed for

  1. handling the liaison to the DialogCaller window, i.e. work as a counterpart to  DialogCaller() :

    • dispatching the start values to the individual input elements when the dialog is launched
    • signaling the DialogCaller not to access the dialog window any more once it has been closed

  2. perform operations internal to the dialog window (e.g. interpreting keyboard inputs, see section Keyboard Inputs)

































DialogFooter() - Syntax

This function has the same syntax as function DialogCaller():
DialogFooter([options])

 options  is a string of keyword options, separated by blank space. A keyword option is of the form  keyword=value  If the  value  comprises blank spaces, it should be bracketed in single or double quotes ( keyword='value'  or  keyword="value" ), depending on the context.

If no options are needed, the function should be called with an empty arguments list:  DialogCaller() 

For a table of the options currently available see sub-section DialogFooter() - Options.

































DialogFooter() - Where to Implement

Function  DialogFooter()  can be called only after the  <BODY> … </BODY>  part of the Dialog file.

































function  Dialog()

This is the function to be called for launching a dialog. Usually this will be done when the user is clicking a  BUTTON  or  SUBMIT :

<INPUT TYPE="button" VALUE="…"  ONCLICK="Dialog( … )">

 …  is the button label that the user will see on screen (e.g.  Dialog  or similar).

































Dialog() - Syntax

You can call this function with one or two arguments:
Dialog("input id's"[,Options])
input id's List of access codes of those inputs you want to expose to user interaction (separated by a blank space). Note that the same codes will be expected as names in the Dialog file for all the inputs to be offered to the user (see point 2 in section Preparing a Dialog File).
This list is needed only for those inputs where you want to have start values presented to the user. If it is ok when the dialog window is popping up with empty inputs, you can leave this list empty.
Options Optional fine-tuning of the function's behavior. For a table of the options currently available see sub-section Dialog() - Options.
































Dialog() - Where to Implement

This function can be called at any place in the main window, wherever you think it's user-friendly. Normally its call will be part of a  BUTTON  or  SUBMIT  input - when the user is clicking the button (or pressing the  ENTER-key, in case of  SUBMIT ) a dialog is launched with the attributes given as arguments:

<INPUT TYPE="button" VALUE="…"  ONCLICK="Dialog('input names'[,Options])">

You can also launch disparate dialogs in a common document, if you call function  Dialog()  with different options  uif= , different button settings (options  noblur  and/or  readonly ) and/or different input names. For details as to the coding of inputs see the following sub-section.

































Dialog() - Inputs Coding

For efficiently preparing your dialog window, and for processing the values returned by a dialog, you will want to know details as to the coding of inputs.

Preparing a Dialog Window

By default, the dialog is launched with dialog window  Dialog.html . This is a very basic dialog-UIF with one input only, a text area as follows:

<TEXTAREA NAME="t" [READONLY] COLS="80" ROWS="25"></TEXTAREA>
The attribute  READONLY  is generated only if  Dialog()  was launched with option  readonly . By default,  Dialog.html  is launched with the following attributes:
status=yes,resizable=yes,left=100,top=70,width=850,height=565
If you want to use the default UIF  Dialog.html , you can do so by calling  Dialog()  without option  uif= . All the other options you can overwrite at will. For a more sophisticated dialog you will need to make up a HTML-file for your own dialog window. Following things should be noted:
  • If you save your HTML-file under any name  xyz.htm , calling the dialog should include the option  uif= :
    Dialog('…',"uif=xyz.htm …")
  • The  NAME=  attributes of all the inputs in your dialog window should be the same as the access codes ID=  of the respective inputs in your main window.
  • Correlated inputs of  TYPE="Checkbox"  or  TYPE="Radio"  should all have the same names.
  • If you want your dialog window to be very user-friendly, you should make each input accessible not only by mouse but by keyboard as well. You can do so by adding the following attribute:
    ACCESSKEY="…"
    It will also be a good idea to let the users know the access key of each input. An easy way to do that is underlining this very letter in the input's label.

The inputs of a dialog can be:

  1. a  SELECT 
  2. a  TEXTAREA 
  3. selected standard HTML input types:
    • checkbox
    • file
    • hidden
    • password
    • radio
    • text

Processing Return Values

The values returned by a dialog can be used in
  1. any object's attributes by Direct Assignment
  2. a  SELECT  whose options will be selected by having the same  VALUE=  as the corresponding return value.
  3. a  TEXTAREA 
  4. selected standard HTML input types:
    • hidden (see Hidden Inputs)
    • checkbox
    • file
    • hidden
    • password
    • radio
    • text

All return values will be taken to be plain ASCII-strings.

For dialog inputs of type  radio  and  checkbox  there is a special interpretation:

 radio 
The return value is the index of the checked button in the radio button group:
  • If no button is checked, "0" is returned.
  • If the first button is checked, "1" is returned.
  • "2" if the second button is checked.
  • etc.
 checkbox 
The return value is a bit pattern with a bit "1" for every checked button, "0" if that button is not checked. The decimal equivalent is returned:
  • If no button is checked, "0" is returned.
  • If only the first button is checked, "1" is returned.
  • If both the first and second button are checked, "3" is returned.
  • If both the second and third button are checked, "6" is returned.
  • etc.

previous    next    top

































Dialog() - Options

Currently the following  Dialog()  options are available:

  1. UIF options
    Options determining the dialog window and its appearance on screen. Similar to the features of standard function  window.open() 
    width=number Sets the width of the dialog window. Default: 850
    height=number Sets the height of the dialog window. Default: 565
    top=number Sets the top position of the dialog window relative to the upper-left corner of the desktop. Default: 70
    left=number Sets the left position of the dialog window relative to the upper-left corner of the desktop. Default: 100
    center=yes|no|1|0 Specifies whether to center the dialog window within the desktop. Default: yes
    status=yes|no|1|0 Specifies whether to add a status bar at the bottom of the window. Default: yes
    resizable=yes|no|1|0 Specifies whether to display resize handles at the corners of the window Default: yes
  2. Dialog options
    Options determining the contents of the dialog and its behavior
    noblur The dialog will have no  Blur  button, i.e. input values are returned only when the dialog is closed. Default: no  noblur 
    readonly The dialog will have no  Close  button, i.e. input values cannot be returned but only aborted (by clicking the  Esc  key). Default: no  readonly 
    For details to button handling, see also Keyboard Inputs
    help="help file" The dialog will have a  Help  button. When the user is clicking it, the given help file will be displayed. For a comprehensive dialog it will be quite user-friendly to provide a help file explaining the details. Default: no help file.
    Notes:
    • This help file can be of type  .htm  or any other file type. The full path should be given unless it is stored in the same directory as the dialog file (UIF)
    • If it is of any browser-compatible type, it will replace the dialog window. To return to the dialog, the users should press the key combination  ALT + !   (You should remind them in your help file!)
    • If it is of any other type, the browser will try to download it, opened with the application associated to the file type.
    • If the user's browser was told before not to prompt  Store to disk or execute right away? , it will be displayed right away.
  3. Processing options
     Options determining processing of values returned by the dialog
    func=
    "custom function([arguments])"    		 Establishes the interrelation of the dialog functions and a custom function (if any). The custom function is triggered in the main window whenever fresh dialog return values are available. Default: no custom function
































    4. function DialogButtons()

    Auxiliary function to

    _ do dynamic creation of dialog buttons (controlled by Dialog Options of function  Dialog() )

    Controlling button creation was shifted to the options of function  Dialog()  for optimum flexibility: Thus it is possible to design only one dialog window but use it for many different dialogs, depending on how it is launched.

    _ integrate a custom function in the dialog window (if any)

    In many a dialog you will want to have the user inputs checked for plausibility or consistency before returning them. Thus in the main window you can process them right away, without caring about their validity - if not valid, they would not have been returned!
































    DialogButtons() - Syntax

    This function can be called out of HTML code by bracketing it in  <SCRIPT> … <SCRIPT> :

    <SCRIPT>DialogButtons(["func([arguments])"])</SCRIPT>

    The optional argument  "func([arguments])"  is a string giving the code of calling a custom function  func() , if any. Optionally this call can be done with its arguments:  func([arguments]) 

    If given, the custom function (with the given arguments, if any) will be called every time the dialog is about to return values to the main window.

    • If returning should be done, the custom function is expected to return  true .
    • If it should be aborted, the custom function should return  false .

    That way it can be used for checking the plausibility of user inputs. If they are found implausible, a clarifying  alert  should be displayed to the user right out of the custom function.

    For example, the dialog pertaining to the trial pad of this article has a plausibility check built in. Leave all inputs empty and try to close or blur the dialog. A message will come up ( Error: All inputs empty ) and the dialog remains on screen.

































    DialogButtons() - Where to Implement

    This function is intended to be called in a table of inputs and their labels, e.g. like in the following coding scheme:

    <TABLE>
  <TR VALIGN=top>
    <TD>Label_1</TD>
    <TD colspan=n>
     <INPUT TYPE="…" NAME="…" ACCESSKEY="…" … >
    </TD>
  </TR>
     :
  <TR>
  <SCRIPT>DialogButtons(["func([arguments]]")</SCRIPT>
  </TR>
</TABLE>

     TYPE="…"  determines the type of input presented to the user ( checkbox ,  file ,  password ,  radio  or  text )

     NAME="…"  are the names by which the individual inputs will be handled by the dialog functions. They should be identical to the identifiers of the respective values in the main window.

     ACCESSKEY="…"  is the attribute needed to make an input accessible by keyboard - a good idea for extra user-friendliness! (Details: see sub-section Keyboard Handling)

     n  is the maximum number of buttons this dialog window will be launched with. (See Dialog Options of function  Dialog() .)