domapi.js is responsible for bringing the DomAPI engine online. It contains support for loading additional units as well as some global vars and constants. It also has the crucial browser-sniffing code used by the rest of the library.
domapi.js contains all the critical methods and properties that make the DomAPI what it is. Without it, none of the components could work. Most every page you create will need to include this file.
This is the only unit that needs to be included using a <script> tag. For every other unit you need to include, you use the domapi.loadUnit() function.
This method extends the array Object to have an deleteItem() method.
This method removes the item at the selected index from the array. The array is assumed to be zero-based, that is, the first item is index number zero.
Example:
myArray.deleteItem(6); // removes the 5th item (zero is the first item)
This method extends the array Object to have an deleteValue method.
This method removes all items in the array that have the specified value. Value can be any primitive type or Object, including elements.
Example:
var myArray = ["dog", "cat", "bird"];
myArray.deleteValue("cat"); // removes the second item
This method extends the array Object to have an indexOf() method. indexOf() returns the zero-based index of a String value contained within the array. If a match is not found, it returns -1.
All arrays you create (when this unit is loaded) automatically have this method. You need not do anything special to install it.
This method extends the array Object to have an pop method.
This method returns the last item in the array and decreases the array length by one. The array is assumed to be zero-based, that is, the first item is index number zero.
The "arg" parameter fed to this method is an inline Object. See below for accepted parameters. Any parameters not listed here that you add may also be attached to any returned Object.
The object returned by this function works as an interface layer between components and the base Elm
Every GUI component in DomAPI inherits all the properties of this class, as well as the elm class.
You never have to explicitly create an instance of the Component class, this is all taken care of by the author of the GUI control.
For instance, the Component class has a boolean property called doRollover as you can see below. If you were to therefore create a
Button instance
on your page, it would have a doRollover property as well, since it inherits it from the Component class.
This function returns a Component object. See there for additional properties and methods.
Available "arg" Parameters:
Parameter
Type
Required
Default
Description
doBGFill
boolean
true
Boolean value that determines whether or not the component's background is transparent.
Actual implementaion depends on the component author.
doBorder
boolean
true
Boolean value that determines whether or not the component's border is visible.
Actual implementaion depends on the component author.
doDepress
boolean
true
Boolean value that determines whether or not the component's animates selections.
Actual implementaion depends on the component author.
doRollover
boolean
true
Boolean value that determines whether or not the component's animates rollovers.
Actual implementaion depends on the component author.
doRolloverFill
boolean
true
Boolean value that determines whether or not the component's fills backgrounds during a rollover.
Actual implementaion depends on the component author.
The "arg" parameter fed to this method is an inline Object. See below for accepted parameters. Any parameters not listed here that you add may also be attached to any returned Object.
This method is the heart of the API. It takes a single parameter which is an inline Object containing all it's constructor parameters.
All Components call this method as well, so anything listed here also applies to Component constructors.
See the tutorial on the Elm Object for more detailed information on this method and the tutorial on using inline Objects.
Example:
var e1 = domapi.Elm({x:100, y:100, bgcolor:"red"});
var e2 = domapi.Elm({parent:e1, type:"IFRAME", w:500, h:300});
Available "arg" Parameters:
Parameter
Type
Required
Default
Description
parent
HTMLElement
body
Existing element you want this new Elm inserted into. Defaults to the document body. Must be a reference, not an id. Use document.getElementById(id) or domapi.getElm(id) to convert an id to a reference.
x
integer
Left position in pixels.
NOTE: If both x and y are omitted, the Elm is relatively positioned. If either or both are present, it's absolutely positioned.
y
integer
Top position in pixels.
NOTE: If both x and y are omitted, the Elm is relatively positioned. If either or both are present, it's absolutely positioned.
w
integer
Width in pixels.
NOTE: If both w and h are present, the Elm's overflow is set to "hidden".
h
integer
Height in pixels.
NOTE: If both w and h are present, the Elm's overflow is set to "hidden".
id
String
Instead of creating a new Elm, will use the HTMLElement identified by this id.
ref
HTMLElement
Instead of creating a new Elm, will use this HTMLElement instead.
type
String
DIV
Type of element to create the Elm as.
DIV, SPAN, IFRAME, P etc....
color
String
initial foreground color (doesn't really apply to Components, just Elms)
bgcolor
String
initial background color (doesn't really apply to Components, just Elms)
skipAdd
boolean
false
Whether or not to insert the Elm into the document immediately. If set to true, it is up to you to call the DOM method appendChild() when and where you want it inserted.
skipStyle
boolean
false
Skips the code that applies initial styling. This can improve performance if not needed. Currently this only includes setting the fore and background colors.
NOTE: If ref or id were passed in the arg param, skipStyle defaults to true instead.
skipPosition
boolean
false
Skips the code that applies initial positioning. This can improve performance if not needed. Currently this includes setting style left, top, width, height, overflow and position.
NOTE: If ref or id were passed in the arg param, skipPosition defaults to true instead.
If the specified unit has not been loaded, this will load it inline (synchronously). Useful for delaying loading rarely used units until they are absolutely needed. This method does nothing if the unit has already been loaded.
The first parameter of this function can be an array of up to four values. If so, it get's it's input from the array. If any are missing, it calculates them just like boxValuesOut() does.
The return value of this function is in CSS format like such:
boxValuesIn(0,5,0,10)
---> "0px 5px 0px 10px"
boxValuesIn(0,5)
---> "0px 5px 0px 5px"
boxValuesIn(Array[5,10,0])
---> "5px 10px 0px 10px"
Many Elm methods indirectly call boxValuesIn(). For instance, elm1.setB([2,4]);
Used internally by elm methods that deal with CSS box properties. The first parameter is a pointer to a style object. The second parameter is a box category such as "border", "padding" or "margin". The third is an optional postfix such as "width".
The function always returns a 4 element array.
Many Elm methods indirectly call boxValuesIn(). For instance, alert(elm1.getB()[2]);
Example:
// example 1 - get array of padding values
var p = domapi.boxValuesOut(elm1.style, "padding");
// example 2 - get array of border widths
var p = domapi.boxValuesOut(elm1.style, "border", "Widths");
This method walks up the DOM tree starting from the Element passed until it either locates a particular node type or reaches the top. If it succeeds in locating a parent node of the specified type, it returns it, otherwise it returns null.
The node type to search for can be either an HTMLElement name such as "TABLE" or it can be a DomAPI node type such as "PAGECONTROL"
Example:
domapi.findParent(elm1, "DIV"); // returns and parent DIV
domapi.findParent(item1, "LISTBOX"); // returns the Listbox parent of an item
Used by the lang.js unit for multilingual messages.
Similar to domapi.getString() but also accepts a string of formating parameters for use with strings that have placeholders. See sysutils.formatString() for information on formating parameters.
When you have a group of nodes that have the same parent (i.e. they are all siblings) this function will return the relative index of a single node. For example, if I had 10 <LI> tags in a <UL>, using this function on the 5th <LI> would return 4. (the first item is always zero)
Example:
// find element's index amongst its siblings
var i = domapi.getNodeIndex(domapi.getElm("itemID"));
This method is essentially identical to calling Microsoft's insertAdjacentElement DOM method, with the following exceptions:
It works in Mozilla as well
It ensures that the element's style.position is "static" first.
This is the method you use when you want to add a component or elm into the page flow. For instance, to add a spinedit component into a <td> with the id "td1", you'd do the following: insertElm(spinedit1,getElm("td1"),"afterBegin");
Now the spinedit is no longer positioned absolutely, and will "flow" with the page. This is very useful for mingling components in with standard form elements.
The where param is a string designating where in relation to the target to place the element. Valid entries are:
beforeBegin
afterBegin
beforeEnd
afterEnd
For instance, to move an image with id "img1" to a place in the document just after a paragraph with id "p1", you'd do the following: insertElm(getElm("img1"), getElm("td1"), "afterEnd");
Given an iframe and an url, this method replaces the content of the iframe's document.
NOTE: The page is loaded in a new thread, to correct for gecko rendering problems.
Parameters:
Parameter
Type
Required
Default
Description
iframe
HTMLElement
Y
url
String
Y
doCacheBuster
boolean
true
If true, DomAPI will add a name/value to the url, designed to be unique enough to warrant the browser to not use a cached version. The name is 'dacb' (Dom Api Cache Buster) and the value is a random number, based on the current client timestamp.
Loads a language (localization) file for use by the system. The default langauge file is English and is loaded automatically. You can change the language used by the system by calling domapi.loadLang(). The language file also controls other system aspects such as date formatting and calendar holidays.
Check the src/lang folder for available languages.
Includes a code unit on the page. name is the unit's name with no path or extension.
All unit names are lowercase.
If a unit is included on a page more than once, all but the first call are ignored.
Refer to domapi.unitLoaded() should you need to know which units have already been included on the page.
You can specify a relative path to the unit if it's not included in the source tree. When this is done, all paths are relative to the src folder. For example: domapi.loadUnit("../../myFolder/myunit");
Note that file extensions are never used. They MUST be .js
Requires core.loadUnit("nodesort"); before can be used!
The "arg" parameter fed to this method is an inline Object. See below for accepted parameters. Any parameters not listed here that you add may also be attached to any returned Object.
This method will sort the siblings of a given HTMLElement.
Example:
// sort the rows of a table based on the second column
var t = domapi.getElm("table1");
domapi.nodeSort({
nodelist : t.rows,
collection : "cells",
collectionIndex : 1
});
Available "arg" Parameters:
Parameter
Type
Required
Default
Description
nodelist
HTMLElement
Y
The list you want sorted. For example pass a <ul> to have items sorted.
direction
integer
sdAscending
Sort direction
Valid entries are
sdAscending
sdDescending
type
integer
stAlpha
Type of date being sorted. Use stAlpha for strings, stNumeric for numbers.
Other sort types may be added later, or you can provide your own compare function.
collection
String
A sub object to sort on. For example, if nodelist was a colletion of <TR>s, collection can be "cells" to sort a particular column.
collectionIndex
integer
0
If a collection was specified, this is the index within it. For example,
if nodelist were the rows in a table and collection is "cells", collectionIndex would be the column index.
low
integer
0
Index to start sorting from. For example, to skip the first item in the list, pass 1.
high
integer
nodelist.length
Index to sort up to.
Leave this parameter off to sort all the way to the end.
compare
Function
Custom compare method. You can provide your own compare method. The engine will pass this method two items from nodelist.
You must return -1,0 or 1.
-1 = first item is less then the second
0 = take no action
1 = second item is less than first
Ensures that a given property has a value and is boolean. If not, it returns the second parameter which is a bool, or false if none was provided. This function is invaluable when writing components or overloaded functions in which not all the parameters may have been passed.
Example:
b = domapi.rBool(b); // make sure b had a boolean value
Ensures that a given property has a value and is an integer. If not, it returns the second parameter which is an integer, or zero if none was provided. This function is invaluable when writing components or overloaded functions in which not all the parameters may have been passed.
Example:
x = domapi.rInt(x,10); // default to 10 if x is not defined
Ensures that a given property has a value. If not, it returns the second parameter which is the default. This function is invaluable when writing components or overloaded functions in which not all the parameters may have been passed.
Example:
name = domapi.rVal(name, "new item"); // default to new item if name is not defined
All Elm methods can have event handlers attached to them.
These handlers apply to all onscreen Elms. The actual target Elm is passed to the handler, as well as the complete argument list sent to the original method.
Hooks are turned off by default. To turn them on, set core.useElmHooks.
Example:
// create handler function
function myMoveToEvent(elm,args){
alert(elm.id);
};
// define the moveTo hook
domapi.regHook("moveTo", myMoveToEvent);
// any calls to moveTo on ANY elm will now call the handler
elm1.moveTo(10,10); // fired myMoveToEvent
Parameters:
Parameter
Type
Required
Default
Description
name
String
Y
Name of the Elm method to hook into. For instance, "moveTo".
handler
Function
Y
Event handler to fire when the named method is called.
Returns the height in pixels that the given text would take in the font provided. Font should be in CCS notation, and will default to the body's font if not provided.
Example:
var h = domapi.textHeight("test string", "8pt sans-serif");
Returns the width in pixels that the given text would take in the font provided. Font should be in CCS notation, and will default to the body's font if not provided.
Example:
var w = domapi.textWidth("test string", "8pt sans-serif");
Returns false if the named unit has not been included on the page. If it has, it returns the path to it.
If you simply need to know if it was included and don't need the path, use domAPILibs.indexOf(name) instead as it has better performance.
Example:
var bool = domapi.unitLoaded("tree");
if(!bool)alert("Tree unit was not loaded");
This method is used to free up all memory used by DomAPI when the page unloads. This will automatically be called when you page unloads, unless you've written your own onunload event. If you do, remember to call domapi.unload() within it.
Controls the depth of the prop clearing code. This runs at onunload and is used to avoid memory leakage by removing any explicit events from your HTML elements. Possible values are 0,1 or 2. 0 turns off the feature - 1 removes only the most common events (onmouseover etc..) and 2 does the most thorough job. The lower the value, the faster the code runs, the higher the value, the more you're protected from memory leaks. 1 is the recommended value.
Can be used to turn off the clearing of the event cache. Each event created using domapi.addEvent() is added to a cache. This is normally flushed during onunload to avoid any memory leaks. Turning this feature off can improve performance but is not recommended.
Document being viewed is using a strict DTD, example: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
DomAPI needs to make adjustments to the way elms are handled in order to ensure your pages look the same in both transitional and strict mode. Transistional is sometimes called "quirks mode".
This was the path that was provided in the domapi_c.js script tag. It is very useful for relative path to graphics.
Most components that use default graphics, will use this path.
See also domapi.imagePath and domapi.themePath.
This property indicates the status of the library as it it loading. If will be false right up until the Window's onload event fires. After that its always true.
Pointer to the Theme currently in use. the default Theme is "system". Additional Themes can be loaded by using domapi.loadTheme() and their apply() methods.
Collection of all themes available. There will be at least one in here representing the default Theme which is stored in the theme property. More are added by using domapi.loadTheme() and then calling their apply() methods.
