The Elm is the heart of DomAPI. It itself is a HTMLElement with custom properties and methods tacked on. Every component in DomAPI is made up of one or more Elms. Elms can be either be created from scratch or existing HTMLElements can be converted to Elms, either by id or reference, all using domapi.Elm().
Each Elm has a property named DA_TYPE which reports what type of Elm it is. Standard ones will have a value of "ELM", while components will usually report their component name. For instance, a Button component has a DA_TYPE of "BUTTON".
DomAPI maintains an array of every Elm created which is useful for looping through all the Elms, or for looking for Elms of a certain type. This array is named domapi.bags.elms and should be considered read-only.
Check out the tutorial on the Elm Object for more detailed information on creating and using Elms.
Elm Constructor
var elm1 = domapi.Elm({
h : null,
w : null,
x : null,
y : null,
id : null,
ref : null,
type : "DIV",
color : null,
parent : document.body,
bgcolor : null,
skipAdd : false,
position : null,
skipStyle : false,
skipPosition : false
});
Constructor Details
Parameter
Type
Default
Description
h
integer
null
Height in pixels.
NOTE: If both w and h are present, the Elm's overflow is set to "hidden".
w
integer
null
Width in pixels.
NOTE: If both w and h are present, the Elm's overflow is set to "hidden".
x
integer
null
Left position in pixels.
NOTE: If both x and y are omitted, the Elm's style.position is undefined. If either or both are present, it's absolutely positioned.
y
integer
null
Top position in pixels.
NOTE: If both x and y are omitted, the Elm's style.position is undefined. If either or both are present, it's absolutely positioned.
id
String
null
Instead of creating a new Elm, will use the HTMLElement identified by this id.
ref
HTMLElement
null
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
null
initial foreground color (doesn't really apply to Components, just Elms)
parent
HTMLElement
document.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.
bgcolor
String
null
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.
position
String
null
Corresponds to the Elm's 'style.position' property.
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.
Requires core.loadUnit("color"); before can be used!
This method is automatically added to the Elm() prototype if the color unit is included on a page. endA is the desired alpha transparency, zero being totally transparent and 100 being completely opaque.
The glideType parameter determines the type of fade to perform. Valid values are:
1 = slow-to-fast
2 = fast-to-slow
3 = linear
Default is 3 (linear) which results in a gradual fade with no acceleration. steps and speed affect how fast the fade occurs and fn is an optional function to execute after completion.
Example:
domapi.loadUnit("color");
...
elm1.alphaTo(50);
Parameters:
Parameter
Type
Required
Default
Description
endAlpha
integer
current alpha value
glideType
integer
3
1 = slow-to-fast
2 = fast-to-slow
3 = linear
steps
integer
50
speed
integer
20
fn
Function
Function to execute upon completion. Can be used to chain together multiple animations.
Requires core.loadUnit("color"); before can be used!
Given a target color, this routine will gradually blend the element's color to match it. Can optionally evalute a passed function upon completion.
See source and examples for more details.
Example:
div1.fadeToColor("bg","#000000",10,10); // fade to black
div1.fadeToColor("bg","#000000",10,10,"alert('done.')"); // fade to black and tell me when it's done
Parameters:
Parameter
Type
Required
Default
Description
kind
String
bg
Specify either "bg" for background color, or "fg" for foreground. Default is "bg".
Returns a four element array containing the width of each border in pixels, starting with the top and moving clock-wise.
See domapi.boxValuesOut() for info.
Example:
var b=this.getB();
alert("Bottom border is "+b[2]);
Returns the element's background color. If color_c.js was included on the page, this function will attempt to resolve color constants such as "red" into their hex equivilant.
Returns a four element array containing the amount of padding in pixels, starting with the top and moving clock-wise.
See domapi.boxValuesOut() for info.
Returns the element's foreground (text) color. If color_c.js was included on the page, this function will attempt to resolve color constants such as "red" into their hex equivilant.
Returns a four element array containing the width of each margin in pixels, starting with the top and moving clock-wise.
See domapi.boxValuesOut() for info.
Returns a four element array containing the width of each padding in pixels, starting with the top and moving clock-wise.
See domapi.boxValuesOut() for info.
Element type.
Standard ones will have a value of "ELM", while components will usually report their component name. For instance, a Button component has a DA_TYPE of "BUTTON". For components, the element will usually have a matching CSS classname, prepended with "DA_". For example, the classname of a button will contain DA_BUTTON.
