Using Pre-coded Modules

For Navigation: Cursor =====>

Using Pre-coded Modules

(demos: IE only)

You think, preparing a document for full online communication is an enormous coding effort? Read on, and you will know how to do it by just a few lines of code!

A pre-coded module is a JavaScript function that generates the HTML-code for a certain application and prepares your user's browser for handling the objects represented by the code generated.

It combines two things:

code generation for the features to be manipulated by your event handlers
setting event handlers (= making them known to the user's browser)

Advantages (all details):

Compact Coding (details)

Whatever complex the HTML-code generated by a pre-coded module, its call is taking a few code lines only. This in turn means saving coding effort when preparing your documents for online communication.
Modifiability (details)

Due to that compact coding, it is easy to spot the coding to be changed if you want to modify a document later. So, if you expect a document to have to be modified frequently, this might be another good reason for using pre-coded modules.
Consistent Layout (details)

By calling a pre-coded module you are getting automatically a consistent layout over all your files. With a large number of documents this is important for good online communication.
Productivity (details)

Compact coding means also saving time when preparing the documents calling pre-coded modules. If you will need to prepare many documents, this could be a reason to develop your own pre-coded modules.

This, admittedly, is partly offset by disadvantage 3.
Saving Download Time (details)

With pre-coded modules, what is really downloaded is only the compact code of calling the module. (Plus downloading the JavaScript/Visual-Basic code of the modules and event handlers, but only for the first file. Once it is stored on your user's PC, it is downloaded no more but the local copy in the cache memory is used to reconstruct the full code from the compact code on each call.) So, in a sense, using pre-coded modules is a kind of "data compression".

This, however, is partly offset by disadvantage 4.

Disadvantages (all details):

IE Browser only (details)

Pre-coded modules are based on DHTML, which is possible in IE only and - partly at least - in some other browsers.

If you want to make your documents cross-browser fit, you might have to prepare different versions for IE and non-IE browsers, plus a doorway page perhaps (see my article "Make your Web Site Cross-Browser Fit!"). This of course will add to your programming effort.
Flexibility Limited (details)

Once a pre-coded module is implemented, it is hard to be changed. Therefore, you should use pre-coded modules not before you are very clear about the HTML-code to be generated, and if you have tested your event handlers with manually-coded HTML features before.
Runtime-consuming (details)

Code generation is taking time. While it is hardly noticeable for one pre-coded module, it might be distracting if many event handlers are responding to the same event. So, in a very complex document, you might consider to use manually-coded HTML instead of calling pre-coded modules.
But then again, by the time the hardware is becoming faster and faster. What seems "too complex" today, might well be a blob a few years in the future.
Programming Effort needed (details)
Preparing a pre-coded module means two things:
- Programming code-generation operations ( document.write(…) or document.writeln(…) )
- Programming event handlers (JavaScript, Visual Basic, etc.)
- You might also have to prepare different versions for IE and non-IE browsers (plus a doorway page maybe, see my article "Make your Web Site Cross-Browser Fit!").
Therefore, pre-coded modules make sense only for features that will be needed in a great number of online documents.

A typical pre-coded module useful in many applications is a function by which you can install a section menu in your document, just by a single function call:

Init ( … )

This pre-coded module will be further elaborated on in the following sections.

Init(…)

The full syntax of function Init(…) is as follows -
compare ... (click!)

function Init([w,[dx,[dy,]]]
"[…@]item_i[[[w,[dx,[dy]]]'[…#]item_i1' | !action_i1, … ]]"
… )

w	Width of submenu level 1. Optional parameter, ignored for single-level menu.
dx	Horizontal displacement of submenu level 1, referring to the left edge of the main menu. Optional parameter, ignored for single-level menu.
dy	Vertical displacement of submenu level 1, referring to the top edge of the main menu. Optional parameter, ignored for single-level menu. dx and dy can also be negative numbers, meaning the submenu will be launched left or above the main menu. (You should be careful with negative displacements: main menu and submenu should still be overlapping, or the user will have no chance to move the cursor from the one menu into the other.) The first three parameters are taken as w, dx and dy only if they are numerically. Note that any of them may be omitted only if the preceding parameter is existing.
…@	URL or (if headed by #) a bookmark to jump to when the user clicks this menu item. Optional part of parameter.
item_i	Text of a menu item; may be any character sequence except the symbols !, &, and , (comma). The only mandatory part of an item parameter.
action_i	Any character sequence that can be interpreted as normal JavaScript code, representing the action to be activated when the user clicks this menu item. Note that action… is an optional part of parameter.

Code Generation

From these parameters Init(…) generates the same code as laid out in article Script-generated HTML Code. For background information look there.

In the same way you can code your own JavaScript function for generating any other code.

Event Handlers

Event handlers are the JavaScript functions laid out in previous articles. For details see the article referring to the feature you are interested in.

Setting Event Handlers

"Setting event handlers" means telling the browser what to do when a certain event occurs, e.g. activating a function when the user presses a key on the keyboard.

It can be done in two ways:

1. Within the <BODY> tag

2. In JavaScript code

document.body.on_event=event_handler;

or, if you want to set several event handlers at once, you can save coding:

with (document.body)
{
  on_event1=event_handler1;
  on_event2=event_handler2;
      :
}

Note the differences:

For setting within the <BODY> tag, the event handler must be enclosed in quotes, e.g.
<BODY on_event="event_handler(); " … >
For setting in JavaScript code, the event handler(s) must be coded without brackets

Advantages:

If you want to set a multi-step procedure to one event, it is easier to do it within the <BODY> tag, separated by a semicolon (;):
<BODY on_event="event_handler1(); event_handler2(); … ">
Coding in JavaScript produces a more compact code.

Disadvantages:

When you need to set several different code handlers, you might find it hard to keep an overview when setting them within the <BODY> tag.
In JavaScript code you have to provide an extra function for calling several handlers in a row, if it's the same event, or if you want to call a handler with different parameters.
In this case it might be better to declare the extra function locally, i.e. nested within the declaration of the pre-coded module.

Coding Scheme:

The basic coding scheme for a pre-coded module looks like this:

function xyz()
{
  var  i;
       :

  // code generation: HTML-environment (+ local event handler)

     document.writeln ('<DIV … on_event="_{event_handler}()">');

     // code generation for all parameters

     for (i=0; i<xyz.arguments.length; i++) // loop over all params
     {  
                        :
        document.writeln (' … xyz.arguments[i] … ');
     }

     document.writeln ('</DIV>');

  // setting (global) event handlers

  function _{event_handler_n}() { … … … …;}
              :
  with (document.body) { on_event1=_{event_handler1};
                         on_event2=_{event_handler2};
                                 :
                         on_{event_n}=_{event_handler_n};
                       }
}

Application Samples

In the following a number of demos and coding schemes are presented for the most frequent applications, one for each type. Try the demos, if you want to understand how they were coded.

Please do spy on the source code! You might sometimes wonder if a demo was really implemented as said 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 "View Source". Look at the top-right screen corner of this article: there you can see Init() in practical use. The section menu of this article is implemented by a slightly modified version of it.

The code of all the demos is marked by a comment like

Single-level Menu

Move your cursor onto the following demo:

Normally, clicking a menu item would link to a bookmark. For not to confuse you in case you are clicking inadvertently, the links are disabled in this demo. You can see the link of the item your cusor is pointing to, when you look at the browser's status bar.

This demo shows the simplest (and probably most frequently needed) application. You can implement it by just one line of code. Look at the following coding scheme:

Coding scheme:

Dual-Level Menu

Move your cursor onto the following demo. When you move the cursor onto the blue item and let it rest there for about ½ second, a submenu pops up:

In this demo the last menu item is associated with an action. Look at the following coding scheme:

<SCRIPT> 
       Init (60,
             "item 1",
             "item 2[item 21;item 22;item 23]",
             "ALERT!alert('ALERT  clicked')")
</SCRIPT>

Multi-level Menu

Move your cursor onto the following demo. When you move the cursor onto a blue item and let it rest there for about ½ second, a submenu is popping up:

This demo shows that a menu hierarchy of any number of submenu levels can easily be implemented by Init() .

Coding scheme:

<SCRIPT> 
menuWidth=…;
displX=…;  
displY=…;

Init (60,
      "item 1",
      "item 2[70,30;item 21",
            "item 22[80,30;item 221;item 222",
                 "item 223[90;item 2231;item 2232;item 2233]]",
            "item 23]",
      "item 3"
     );
</SCRIPT>

Hints for Using Init(…) :

By giving numbers for global variables menuWidth, displX and displY you can modify the width, horizontal and vertical displacement of the section menu, referring to the top-right corner of the screen.
"…, …, …" are numbers giving the width, horizontal and vertical displacement respectively of the submenu, referring to the top-left corner of the parent menu. In a single-level menu they are ignored. (Use global variables menuWidth, displX and displY instead).
Menu items can be given in plain text or in any HTML-code. If you have quotes within your HTML tags, however, make sure they do not interfere with the surrounding quotes.
By default, a JavaScript string cannot stretch beyond a line break. If you want a line break within a string, you need "line splicing" by coding a back-slash at the end of the line, except the last line of the string. If you want your document to be displayed also in a non-IE-browser, be sure never to use more than one line spliced to a second line. Some other browsers than IE stop displaying when a second line splicing is encountered. A good remedy is to use global variables. If you want to make your document cross-browser fit, you should consider creating separate versions for IE and NS and combining them by a doorway page)
1. If you want to assign a submenu to a menu item, code it as [ … ] right at the end of the item text.
2. You can also assign any JavaScript statement to a menu item. Code it as !… … … right at the end of the item text.
3. By default, the menu items are linking to bookmarks #1 , #2 , etc. ( #11 , #12 , etc. for a submenu of level 1, #111 , #112 , etc. for level 2, and so on). However, they can also be made to link to any URL or bookmark. For coding, separate the link destination from the item text by @ .
4. Link destination and assigning a submenu or JavaScript statement to a menu item can be combined. By default, the link of an item with a JavaScript statement is disabled. If you want to link to a destination after execution of the JavaScript statement, the destination must be given explicitly.

Delivery

Probably the best way of delivery of pre-programmed modules in DHTML is, handing out a HTML template and a subdirectory where all the external files that are called by it (the "externals") are stored. As a matter of course, the template should be modified such that the externals are expected in that subdirectory.

The easiest way to prepare it for shipment is:

Develop the DHTML functionality as usual by inspecting it in the target browser.
When you are done, store it to your delivery medium. In a modern system like Windows 2000 not only the .htm-file is stored but also an "associated" subdirectory with all the externals. The name of the associated subdirectory is …-Files (or …-Dateien , or whatever your local language is). An "associated" subdirectory is one that is automatically copied/moved/deleted along with the .htm-file, at least in modern systems. In older systems it might be necessary to copy/move/delete them manually. Note: Not "all the externals" are stored in the associated subdirectory but only those called right from the HTM-code. If some externals are occurring only within your JavaScript functions, they have to be added by hand. Quite obviously, you need to modify the calls within the JavaScript functions as well: Place a prefix …-Files\ in front of the external's name.
Your delivery medium might be, for example, a diskette. Then the .htm-file "… .htm" will be stored in its root directory, along with the associated subdirectory.
If you want to deliver by email, you should pack the .htm-file and the associated subdirectory to an archive file (e.g. "… .zip"). Thus you have only one attachment file, holding all the file plus externals, even maintaining their directory structure.

Linking to any URL:	http://…@item_text
Linking to any bookmark:	#…@item_text