Contact Us

Elm Overview

An Elm is an ordinary HTMLElement that has been given special properties and methods (referred to as "members") These members allow Elms to behave much more like traditional GUI elements. They allow Elms to be manipulated in an OOP manner that makes building DHTML GUIs a much more approachable task. Elms form the basis for all components in DomAPI, but they can also be created as stand-alone objects.

Any onscreen element can be converted to an Elm. Elms can also be created dynamically at runtime. Elms created at runtime can be added to the document, or they can exist in memory only. They are very flexible little critters.

Introduction to domapi.Elm()

The function domapi.Elm() is used to both convert existing elements and to create new Elms. domapi.Elm() takes a single parameter which is a Javascript Object, typically created in an inline fashion. (for more information on inline objects, see the Appendix entitled "Working with Function Args").

Every property of the Object passed to domapi.Elm() is optional, including the Object itself. The following table lists the properties that domapi.Elm() will respond to including a brief description of each and what the default values will be if the property is omitted. The properties below are listed in alphabetical order. The actual ordering of the properties is not important in practice.

Note that this is not the complete list of properties. Refer to the documentation on domapi.Elm() for the fullest and most up-to-date material.

Property	Default	Description
bgcolor	null	Background color to apply to the Elm. Only applies if skipStyle is false.
color	null	Text color to apply to the Elm. Only applies if skipStyle is false.
h	null	Height in pixels to assign to the Elm. Only applies if skipPosition is false. If both w and h are not null, the Elm''s style.overflow is automatically set to "hidden".
id	null	If you pass the id of an existing page element, that element will be transformed into an Elm instead of creating a new one.
parent	document.body	Parent element to append the Elm to. Only applies if we are creating a new Elm and skipAdd is false. If parent is null, the Elm is attached directly to the page body.
ref	null	If you pass a reference to an existing page element, that element will be transformed into an Elm instead of creating a new one.
skipAdd	false	If true and we are creating a new Elm, the Elm will not be added to the document. This can cut down on load times when building compound elements, or when you need to apply alot of styling to an Element before showing it onscreen. Use the appendChild() DOM method to add the element to the page later if needed.
skipPosition	false	If true, the Elm will not be sized or positioned.
skipStyle	false	If true, the colors will not be applied to the Elm.
type	"DIV"	Type of elm to create. Only applies if we are creating a new Elm, not using an id or ref. Type can be any valid HTML element. Default is a "DIV".
w	null	Width in pixels to assign to the Elm. Only applies if skipPosition is false. If both w and h are not null, the Elm''s style.overflow is automatically set to "hidden".
x	null	Left position in pixels to assign to the Elm. Only applies if skipPosition is false. If both x and y are null the Elm is positioned relatively, otherwise it will be positioned absolutely.
y	null	Top position in pixels to assign to the Elm. Only applies if skipPosition is false. If both x and y are null the Elm is positioned relatively, otherwise it will be positioned absolutely.

Creating New Elms

Here are some examples of using domapi.Elm() to create brand new Elms:

var e1 = domapi.Elm();   // uses all defaults
var e2 = domapi.Elm({}); // same thing, uses all defaults

// This next one creates a 100x100 pixel element into an existing
// HTML element with the id of "main".  The new Elm is placed
// 50 pixels from the left and top of the "main" element.
var e3 = domapi.Elm({
  parent : document.getElementById("main"),
  x      : 50,
  y      : 50,
  w      : 100,
  h      : 100
});

Here is an example of using delayed creation. We want a red DIV with white text that reads "hello world" to be positioned at 100, 100. We do not want the Elm placed into the document flow automatically, but want to add it manually ourselves after we have set the innerHTML to be "hello world". We want the width and height to be automatic:

// create the Elm
var e = domapi.Elm({
  x       : 100,
  y       : 100,
  color   : "white",
  bgcolor : "red",
  skipAdd : true
});

// set the text of it
e.innerHTML = "hello world";

// manually add it to the document
document.body.appendChild(e);

Notice that you can break the Object out onto different lines to help make it more readable. Perfectly legal.

Converting Existing Elements to Elms

There are two ways you can convert an existing element to an Elm. One is to pass an id to domapi.Elm(), the other is to pass a reference. Whichever you use is up to you and whatever is convenient at the time. If you already have a reference to an Element, then passing that is faster than passing the id, otherwise both are about the same.
The following example shows many ways to convert an Element to an Elm. In this example, we assume we have a form element named "input1" that we want to be an Elm:

// passed by ref
var e = domapi.Elm({ref : document.forms[0].elements["input1"]});

// passed by id
var e = domapi.Elm({id : "input1"});

// passed by existing ref (same effect as pass by ref)
var e = document.forms[0].elements["input1"];
domapi.Elm({ref : e});

Converting existing elements into Elms using id or ref is a powerful technique for creating applications. We'll return to this concept later once we've been introduced to Components.