( Please read this before considering using it)
Cohabitation with other code
MJSLIB modules initialization
MJSLIB implements a registration mecanism: when a module is loaded, it simply get registered into the framework and postpone the rest of its initialization to a time where the whole document is loaded. The main.js module is first loaded. It binds a "onload" event to the main initialization code. When it receives the event, it goes over all entry in the registered modules, and call their individual initialization function.
The initialization part of MJSLIB modules usually consists of searching relevant elements within the document, and attach behaviors to them.
Where to place your code
Separating JavaScript code and HTML document is surely a wise approach. You can add your own module after loading the MJSLIB files you want to use:
<SCRIPT LANGUAGE="javascript" src="mjslib/main.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="mjslib/debug.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="mjslib/formval.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="mjslib/date.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="mjslib/fieldgroup.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="mjslib/toc.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="mjslib/menu.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="mjslib/image.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="mjslib/tooltip.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="mjslib/dumper.js"></SCRIPT>
<SCRIPT LANGUAGE="javascript" src="js/mylib.js"></SCRIPT>
When to run your code
You can use the MJSLIB registration mecanism for your own modules, this is a nicer than hooking the "onload" event from the HTML code:
function InitMyModule()
{
// At this point, the document is loaded
}
mjs_registerModule("mymodule",InitMyModule);
A few API calls need to be done *before* this initialization occurs,
such as registering new data type for the form validation module. This
aspect is documented in relevant module pages.
MJSLIB Coding "style"
Naming, prefixes
To avoid namespace conflicts, most variables and functions names start with one of those prefix:
| mjs_ | This denotes a function which is part of a public API. You can use those functions from your own javascript code, we'll ensure a compatibility across versions. |
| _mjs_ | Private functions. Do not use those functions from your code; their existence and prototype may change in future revision of this toolkit |
| gMMM_ | Global variable of a module (MMM denotes the module name). Do not use them from your code; use documented API instead. |
Automatic IDs
A lot of features within this library rely on the existence of the ID attribute of elements. When this attribute is missing, instead of failing the feature, an internal mecanism automatically allocates an ID for its needs and tie it to the element. The ID is choosen so that you can get a rough idea of which elements it belongs to by looking at it; this helps the debugging when error messages report ID values that you did not set yourself.
The function which allocate the ID is implemented as mjs_allocateElementID(element) in the module main.js.
Associative arrays
As a perl programmer, I rapidly became a fanatic of HASH objects (AKA associative arrays). This data type is available in most modern programming languages. I personnaly find them extremely versatile and useful for many purpose, hence the use in many places of this library. I especially use them to implement various registry to keep track of the elements I need to care about within a specific module.
For example, the formval.js module keeps track of which UI element having validity tests belongs to which form, so that it can quickly go through them without reparsing the HTML tree. This is done by storing this information in the global gFV_formRegistry variable; the index (hash key) is the ID of the form element.
If you start using this yourself, be aware that there is a subtle and important differences between "var myHash=[];" and "var myHash={}". The first syntax is equivalent to "var myHash=new Array()", and the second is an alias for "var myHash=new Object;".
In javascript, every instance is an associative array, and contains keys that can be accessed this way: myObject['keyname']. A very odd side effect of the javascirpt runtime is that when you add a method to a class, the name of this method will appear as new key for its instances. For example, if you create the method "myMethod" to the class Array, every Array instance will have the key "myMethod" set to the function that implements the method. If you go through the list of keys for the object (with a for(x in Y) construct for example), you will encounter this value which you did not set manually, and this is something you probably don't expect.
Indirection functions
When reading the code, you'll probably see a lot of function calls that could be replaced by direct access to DOM value or method. This is intentionnaly done this way in order to erase variations between browsers as well as making the code easier for reading (well, this is probably debatable, just my own humble point of view).