Providing user interactivity in an online document is a trade-off: Not too little, so the users can make real  hands-on experience . Not too much, so the author does not have to detract too much time from writing the text, just for making the message vivid. This article will show you a way to make it an easy job.

When talking about providing user interactivity in your online documents - let's not forget that this is taking quite some effort!

Except for very basic user interactivity (such as  alert() ,  confirm() ,  prompt() ) it's quite laborious if you want to implement it from scratch. (For simple operations, see my article How to Provide User Interactivity. For more complicated dialogs, see Dialog - Easy User Interactivity Anytime.)

What's needed is a software component that is easy to use like an  alert() , yet flexible like a full dialog. I developed such a software component: SubDlg() . With it you can have:

1. different styles (details + demo [IE browser only]: section Coding - Style)
2. none or different titles (details + demo [IE browser only]: section Coding - Title)
3. different contents (details + demo [IE browser only]: section Coding - Contents)
4. different buttons (details + demo [IE browser only]: section Coding - Buttons)
5. permanent or temporary display (details + demo [IE browser only]: section Coding - Duration)
6. custom actions  before  display (details + demo [IE browser only]: section Coding -  onopen )
7. custom actions  after  display (details + demo [IE browser only]: section Coding -  onclose )
8. easy coding of return value (details + demo [IE browser only]: section Coding - RETURN)
9. SubDlg  usage by keyboard (details + demo [IE browser only]: section Coding - KEY)
10. using images instead of buttons (details + demo [IE browser only]: section Coding - Graphic Buttons)

Handling

If you ever wanted to implement user interactivity in an online document, you will have encountered it: You had a clear idea of what dialog you wanted to present. It would be easy to implement by a few line of HTML code. But the presentation itself would have required an enormous effort. What you needed was a "vehicle" handling all that effort but giving you any freedom as to the contents.

A  SubDlg()  is such a vehicle. It can be called any time similar to a standard  alert() . By default, it behaves just like that. For a detailed comparison of  SubDlg()  and standard  alert()  look into this footnote .

A major edge of  SubDlg()  is the fact that you can implement a complete online document - including all user-interactivity - in one HTML-file, even for rather complex dialogs. Before there was  SubDlg() , you could have

• either a self-contained online document, yet pretty simple user interactivity - only a few very basic dialog steps (see How to Provide User Interactivity)
• or a full dialog, yet with several external files. Not so easy to manage, and hard to maintain when things are changing (see Dialog - Easy User Interactivity Anytime).

Now, with  SubDlg() , you have the best of both worlds.

Coding

Coding - Style

1. Semi-permanent Style Change: For your  corporate identity  you might want to have a uniform default layout, every time a  SubDlg()  is launched in an application. Then you should change the Semi-permanent Style Sheet (look into this footnote).
2. Temporary Style Change: If you feel, a  SubDlg  should give a different impression, then you should use the option  style=  to have a different layout for this launch only. (For details look into this footnote.)

• With the cursor anywhere on the white background of the screen, click the right mouse key. Your browser's context menu will pop up.
• Within the context menu, click the item  View Source Code . Your system's default browser will pop up with the HTML code making up this document.
• Search for  <!-- demo 21 -->  In the next lines you will see the source code of the following demos.

Coding - Title

By default, a  SubDlg  is presented just like a standard  alert  box - but without a title bar.

You can include a title bar by using option  title= . It can hold plain text (with some HTML tags intermingled, if you want) and/or any HTML construction. By default, its style is controlled by the line introduced by  .tempmsgTitle  in file  OnlineComm.css  You can modify that style semi-permanently, uniformly for all  SubDlg  within the document.

For text and rather simple HTML constructions, a linear string will be all you need. For more complicated HTML constructions, however, you will prefer  Indirect Coding  (see Appendix 2: Indirect Coding).

By the following demos you can see what this option is good for. (If you want to spy on the source code, search for  <!-- demo 22 --> . In the next lines you will see the source code of the following demos.)

Coding - Contents

Just like the title bar, the contents can be plain text (with some HTML tags intermingled, if you want) and/or any HTML construction. Usually this will be a collection of standard HTML  <INPUT>  tags, combined with some text. Such a "custom SubDlg" will be useful if you want to prompt the readers for their inputs to a user interaction.

For text and rather simple HTML constructions, a linear string will be all you need. For more complicated HTML constructions, however, you will prefer  Indirect Coding  (see Appendix 2: Indirect Coding).

The following demos will show you what the contents can be.

If you want to spy on the source code, search for  <!-- demo 23 --> . In the next lines you will see the source code of the following demos.

Coding - Buttons

By default, a SubDlg is presented just like a standard  alert  box (one button "OK").

In many applications you will want to have a minor modification: two buttons ("OK", "Esc"). You can have that by simply adding the option:

If you want a more complex array of buttons, you can implement it by the option:

 … …  can be any HTML-code you want to implement your buttons - e.g.  <INPUT TYPE=Button … >  or whatever you like.

A sample SubDlg with three buttons ( Yes ,  Don't know ,  No ) you can see when you click on the following buttons. (If you want to spy on the source code, search for  <!-- demo 24 --> . In the next lines you will see the source code of the following demos.)

Coding - Duration

One thing that is not very user-friendly about standard  alert()  is that all the application is stopped once it is launched. The user can do nothing else but click the  OK-button or change to another application.

In contrast to that, a  SubDlg  can be limited to be on screen only a certain number of seconds. This will be useful for:

• A quick message that should not block the screen longer than needed for reading it.
• A custom dialog that is relevant for a certain time span only. If not used, it should not remain on screen forever, but be closed automatically after some time.

The remaining number of seconds is counted down in the bottom-right corner. After this time, the sub-dialog is closed automatically. Whatever the duration - if the user clicks any of the keys, the  SubDlg  is closed immediately.

By a  no-button sub-dialog  with any  duration  you can add more user-friendliness to your application:
A frequent problem in online communication is, you want to give the users a minor information, relevant for the moment only. With standard  alert()  the users are forced to click the  OK-button, or the alert box would stay on screen forever. With a timed  SubDlg() , however, the users need to do nothing. - Try the second demo! (Notice the blank space in the option  buttons=« »  !)

If you want to spy on the source code, search for  <!-- demo 25 --> . In the next lines you will see the source code of the following demos.

(When the duration is counted down, the SubDlg will close automatically.
If you don't want to wait that time, you can close it by clicking  OK .)

Coding - onopen=

When the contents of your SubDlg are a custom dialog, you might want some action to be taken before the SubDlg pops up on screen. (A typical example would be, to have an input set to any default value - prompting the users to overwrite it.)

This can be done by the option

 … … : JavaScript code implementing the action to take before the SubDlg will be opened.

The following demo will show you how to set an input to any default value before it is open to the user's inputs.

If you want to spy on the source code, search for  <!-- demo 26 --> . In the next lines you will see the source code of the following demos.

Coding - onclose=

When the contents of your SubDlg are a custom dialog, you will usually want some action to be taken after the SubDlg is closed. (In most cases, this will be any process depending on the return value of the SubDlg - accessible by the global variable  subRetVal .)

This can be done by the option

 … … : JavaScript code implementing the action to be taken when the SubDlg is closed.

The following demo will show you how a simple example of how to process the return value of a SubDlg.

If you want to spy on the source code, search for  <!-- demo 27 --> . In the next lines you will see the source code of the following demos.

Coding - RETURN

It's actually quite a complicated procedure when a  SubDlg()'s button is pressed, resulting in closing the  SubDlg()  and returning any value that can be further processed by using the global variable  subRetVal .

To make it more programmer-friendly, all that complicated stuff is kept away from you. All you have to do is coding a custom HTML attribute:

The following demo will demonstrate you how simple it is to code return values for  SubDlg .

If you want to spy on the source code, search for  <!-- demo 28 --> . In the next lines you will see the source code of the following demo.

Coding - KEY

What kind of people is your application aimed at? Are they familiar with computers, will they like fine-pointing with the mouse? Then you will have an easy job. However, many people tend to dislike computers, just because they are required to do that. They would prefer to press any key on the keyboard instead.

Well, you can give them what they want. To you, that's only a minor coding effort:

1. At the end of your online document, between </BODY> and </HTML>, insert a code line:
   <SCRIPT>SubDlg_Init()</SCRIPT>
2. To each closing button of your  SubDlg()  add an attribute:
   <INPUT TYPE="Button" KEY=…>

   E	… is the character represented by the intended key. To avoid any problems with confusing keys, in the current  SubDlg()  version they are limited to printable chars only.

Typing the key characters will be interpreted like closing only if a keyed  SubDlg()  is on screen. If not, they have the usual effect. - Obviously, a SubDlg() prompting for typing inputs should not have keyed buttons.

The following demo will give you a simple example of how to implement key handling for  SubDlg . If you want to spy on the source code, search for  <!-- demo 29 --> . In the next lines you will see the demo's source code.

Coding - Graphic Buttons

The preceding demos were all implemented by real buttons whenever we were talking about "buttons" - just for clarity. If you want to give your  SubDlg()  application some extra user-friendliness, however, you will want to design graphic faces for your buttons. Thus perhaps even creating sort of  corporate identity : all software coming from you has a special look-and-feel!

To that end, all you have to do is

1. prepare the button faces in form of  .jpg  or  .gif  images
2. store those images in the same directory as that of your online document
3. declare the images in place of buttons

All the rest will be done automatically.

The following demo will illustrate how to implement graphic buttons for a  SubDlg . In this demo, also the RETURN custom attribute (see Coding - RETURN) has been used.

If you want to spy on the source code, search for  <!-- demo 210 --> . In the next lines you will see the source code of the following demo.

Requirements

• Hardware
• Browser
• include
• call

Requirements - Hardware

• Keyboard:
  Most of the Custom Inputs require keyboard typing.
  Will all your users have a keyboard?
• Mouse:
  All of the Custom Inputs are designed for mouse input.
  Will all your users have a mouse?
• Monitor - Colors, Screen Resolution:
  Some of the Custom Inputs assume multi-chrome monitors.
  Will all your users have a multi-chrome monitor?
  In general, you should be aware of the monitors' size and screen resolution. What will they be at your users'?

Requirements - Browser

Requirements - include

Of course, you should make sure that the JavaScript-File  Input.js  really is in the current working directory on your server. If not, you might have to alter the path, e.g. <SCRIPT SRC="../JS/Input.js"></SCRIPT>

If you want to combine SubDlg()  with any of the other software components described in the other articles of these archives, you should declare them one after the other. E.g.:

Requirements - call

<SCRIPT>SubDlg( … );
    :
SubDlg( … );
    :
SubDlg( … )</SCRIPT>

Appendix 1: Keyword Params

SubDlg()  is based on a software technology that is different to standard programming languages (such as  JavaScript ).

In standard programming languages you can control a function only by  positional parameters . That is, the significance of a parameter is given by its position in the parameter list: the first parameter, the second parameter, etc.

To the human programmer, that's fine as long as there are not more than some 6-10 parameters. Beyond that, it's but too easy to overlook a parameter. Consequently, all the following parameters would be interpreted incorrectly.

That's going to be a problem especially when you have a significant parameter at, say, position 29 - whereas the parameters of position 21 to 28 are not significant. So, to the human mind the most obvious thing would be to leave them out. Alas, then your significant parameter of position 29 would be interpreted as if it were at position 21. Not exactly what you want!

Therefore, the options of  SubDlg()  (and all the other software components presented in these archives) use a software technology called  keyword parameters  (Exact formalism: see this footnote.)

Appendix 2: Indirect Coding

SubDlg()  is very powerful. For title, contents and buttons it can display anything from plain text up to the most complicated HTML constructions. This is more, in fact, than what can be coded simply as a linear string (holding the HTML code of the construction).

Therefore the concept of  Indirect Coding  was introduced:

• Within brackets  <DIV id=…> … </DIV> , the desired HTML construction is coded - as simple as in a normal HTML document.
• Prefixed by  @ , the identifier  …  declared in  id=…  of the opening  DIV-tag is used for the parameter in case, e.g.:
  <DIV id=title> … </DIV>
  <DIV id=contents> … </DIV>
  <DIV id=buttons> … </DIV>
  SubDlg(@contents,"title=@title buttons=@buttons")
• You will not want your page to be defaced by these DIVs. So you should hide them:
  <DIV id=… STYLE="display:none">
      :
  </DIV>
    :   indicates the HTML code of your construction.

Footnote: User-friendliness  SubDlg()  ← →  alert()

1. By  SubDlg()  any dialog contents can be presented that can be implemented in HTML: text (any font/style/color), standard inputs, UserInputs (see my article: Pedagogical Background of Online Communication), images, …
   By standard  alert()  only plain text can be presented.
2. Similarly, any text or HTML construction can be presented in the title bar of a  SubDlg() .
   In standard  alert()  the title bar cannot be used productively.
3. As well, any combination of standard buttons (or any other HTML construction) can be presented in the buttons bar of a  SubDlg() .
   In standard  alert()  you have only one button,  OK . If you want a combination of  OK  and  Esc  button, you have to change to  confirm() . Other button combinations are not possible in standard message boxes.
4. The  SubDlg()  box can be presented in any style (color, borders, … ). By the mere look of a dialog box a sense of the message can be conveyed.
   A standard  alert()  or  confirm()  box always looks the same: light-grey, with plain text in the default font.
5. Technically,  SubDlg()  is a  modeless dialog  - meaning that the user can continue with the application as usual. Even when another  SubDlg()  is launched later - the old dialog box just changes its layout but stays on screen.
   Standard  alert() , however, is a  modal dialog . The application is completely halted, not even the main window can be minimized or closed. The user has to click the  OK  or  Esc  button first, thus closing the dialog.
6. The display of a  SubDlg()  can be limited to any duration, then it will be closed automatically. By clicking any of its buttons, the user can close it before.
   Whereas a standard  alert() , remains open all the time, until the user clicks any of its buttons or presses the  ENTER- or  Esc-key.
7. SubDlg()  can be moved across the screen by dragging at any place where the cursor is . That is, at any place within the dialog box except the title, the contents or the buttons.
   Standard  alert()  can be moved only by dragging in the title bar.
8. SubDlg()  at first will pop up in the center of the screen. From there it can be moved to any other place on screen, and it will stay there: If some other  SubDlg()  will be launched later, the dialog box will change but at the same place as before. (Except if the main document has been scrolled meanwhile - then  SubDlg()  will follow suit.)
   Standard  alert()  always pops up in the center of the screen.
9. 
   SubDlg()  can be resized when the cursor is of any of the  …-resize  types: Within a margin of some 20 pixels inside the sub-dialog box, the cursor turns to any of these types. Which one, is depending on the place within the box: Horizontal/vertical arrow inside of a vertical/horizontal edge, slant arrow inside of a corner. By dragging the sub-dialog box will be resized then, as indicated by the cursor type.
   Farther inside than some 20 pixels, the cursor turns to the  move  type (). Dragging means moving the sub-dialog box then.

1. SubDlg()  is a JavaScript function with (currently) 9 parameters, only one will of which be used every time. The others will be needed only if you want to implement a certain effect. Therefore,  SubDlg()  is based on keyword parameters. (For details on keyword parameters, look at Appendix 1: Keyword Params.)
2. Some of the parameters ( contens ,  title ,  buttons ) can get quite complicated to implement as strings, requiring a delicate nesting of  '' ,  ""  and  «»  brackets. Therefore  indirect coding  was introduced:
   • Within brackets of  <DIV ID="…" STYLE="display:none">  and  </DIV> , code it in the usual way.
   • In  SubDlg() , code a reference to it by  @…  (preceded by the keyword, if needed). "…" is the identifier of the  <DIV id=…> </DIV>  where you coded it in the previous step.
3. The contents of a  SubDlg()  can be plain text and/or any HTML construction. You can use that to give your messages a more communicative layout. E.g. important words could be bold, a subject comprising several points could be a bulleted list, etc.
4. You can use option  style=  to convey a subtle message. For example, neutral information boxes could be in default (lightgrey) color, warnings in pink color, error messages in red.
5. You can have your own construction of the title bar. Thus the title could be e.g. text (with HTML tags intermingled, if you want), combined with buttons. For an example, look at the close-button of section Coding - Title
6. You can have your own combination of buttons (or any other HTML construction you want to use instead). For example, look at section Coding - Buttons
7. You can give your applications an extra user friendliness by making sure that the dialog box is closed automatically. Though the user can close it before, by clicking any of the buttons. (See  Coding Duration )
8. You don't have to make the dialog box close every time.  SubDlg()  implements a modeless dialog: Even if another  SubDlg()  is launched while the old dialog box is still open - the box's layout changes, nothing else.

• Click the bottom item in the SectionMenu (top-right corner of the screen), named "Semi-permanent Style Sheet".
  If the file type  CSS  is defined in your system, the file  OnlineComm.css  will be opened in your system's default browser right away. If not, you will be prompted first:  Open, or save to disk?  Now you should select  Open . (Have no sorrow - it's your own system's default browser what it will be opened in!)
• Search for the line introduced by  .tempmsg 
• In this line, within the brackets  { } , modify the default style as you want. Code it in the usual CSS-notation.
• Finally, don't forget to save the modified file.
• Next time a default  SubDlg  is launched, it will be in the new layout.

1. Keyword parameters may be coded in any order.
2. The significance of a parameter is given by its prefix (the "keyword").
3. Insignificant parameters can simply be left out.
4. Keywords are case-sensitive. They must be coded exactly as given in the documentation.
5. Keyword parameters ("options") can be simple  keyword  or pairs of  keyword  and  value , separated by  = .
6. Individual keyword parameters must be separated by at least one blank space, if the preceding  value  is not bracketed.
7. In some cases, a keyword parameter might have a few positional parameters. (Their order is significant!)
8. A parameter value may be coded with or without brackets. If it comprises a blank space, however, it must be bracketed in  '' ,  ""  or  «» .
9. The outermost brackets of an option string must be those standard to JavaScript ( ''  or  "" ).
10. If the symbols  «  and  »  are not on your keyboard, you can enter them by:
    • Press the  ALT -key, and
    • on the numeric keypad type "174" (for  « ) or "175" (for  » ).

    E	Deciding on how to nest  "" ,  ''  and  «»  brackets, to code a single apostrophe, or to factor out an expression, can be quite a hairy matter sometimes. For a good example of that, look at the coding of  close_button  in the sample of section Coding - Title

11. The closing apostrophe of the last keyword parameter (be it  ' ,  "  or  » ) may be omitted.
    (Not recommended, however: If the option string is expanded some time later, it is too easy to overlook that!)

In some applications you will want to display some contents, but make sure that the users cannot copy them to clipboard. Thus protecting them from being further processed.

You can do that simply by Indirect Coding of a nested <DIV> which is disabled for selection:

<DIV ID="noselect" STYLE="display:none">
<DIV onselectstart="return false"> … (contents to protect) … </DIV>
</DIV>

	:

SubDlg('@noselect');