Class JObject

Defined in jobject.js

JObject is a featureful object system for Javascript or ECMAScript, primarily intended for use by XBLinJS. Generally, for something like this NIH syndrome hits full force, so I don't really expect anyone to use this. Nevertheless, I document it here, as I intend to use it and others may need to consult this.

JObject abstracts out the parts of the Widget class that aren't really Widget specific, namely:

• The argument passing convention, including the specifying of defaults.
• The initialization sequence (abstracted into .initialize, use of the "prototypeOnly" parameter to nicely create and pass prototypes).
• Most of the .setAttribute machinery, with extensibility.
• deriveNewJObject for derivation from old ones.
• Automatic (optional) creation of properties from attributes, in interpreters that support it.

Like I said, NIH probably means you'll never use this. However, JObjects do work very nicely with Widgets, mostly due to sharing their ideas on .setAttribute and such.

Note that JObjects have no connection to DOM nodes, or in fact anything else; they are pure Javascript/ECMAscript objects.

For reference, "JObject" stands for a Jerf (or Jeremy Bowers) Object; I couldn't think of a better name than Object (which is taken and should not be modified on such a grand scale), or something that was misleading ("SuperObject"?).

Field Detail

CAN_CREATE_PROPERTIES

Object CAN_CREATE_PROPERTIES

Set to true if this Javascript instance can create properties, false otherwise.

This should almost certainly not be set manually.

className

Object className

The name of the class of this object.

All JObjects get stored in JObjectNameToType, where they can be retrieved by their className.

defaults

Object defaults

The declared defaults, defaulting to {}, of course.

Children wishing to override this declare their defaults as key: value pairs in this object. Upon widget construction, they will be added to the 'atts' parameter if they do not already exist.

initOrder

Object initOrder

The initialization order for .init to set the remaining attributes; an Array of strings.

Default is to define no special order.

TRY_TO_CREATE_PROPERTIES

Object TRY_TO_CREATE_PROPERTIES

Indicates whether to auto-create properties.

This should not be directly manipulated under normal circumstances because it can not be counted on cross-platform, but you should && it with CAN_CREATE_PROPERTIES, which will be true if the JS lets you create properties and false otherwise. If you do this, you can change it with subclasses; XBLinJS uses this for instance in its Flavors.

This ships defaulting to "off"; replace the false with a true to make this happen.

JObject

JObject(atts, prototypeOnly)

JObject - a featureful object system for Javascript/ECMAScript

createDefaultProperty

void createDefaultProperty(propName)

If we're in an environment that supports Javascript properties, create a property for "propName" that sets and gets the property using .setAttribute and .getAttribute.

declareVariable

void declareVariable(varName, varType, value, extra)

This declares a Variable for this widget.

Normally, this is private and you should use the .Variables support for declaring variables, but it is permissible to call this manually.

Parameters:
varName - The name of the variable, which is used in .*Attribute.
varType - A reference to a Variable implementation class. By default, a ValueVar will be used.
value - The initial value of the variable, which will be set if it is anything other than undefined.
extra - Any extra initialization needed by some Variable type.

get

Object get()

Synonym for "getAttribute".

getAttribute

Object getAttribute(name)

Gets the chosen attribute through the cascade lookup described in detail in the HTML documentation.

Summary: Looks for a property defined via "get_[name]" method, a Variable, an inherited value, or an attribute on the Widget object.

Parameters:
name - The name of the attribute to retrieve.

init

void init(atts)

The default JObject initialization routine.

The default initialization routine is to call all attributes with .setAttribute(key, value). If an .initOrder, an array of key names, is given, those attributes will be processed in order, then all remaining ones will be processed in hash order.

Parameters:
atts - The atts object for the initialization sequence.

initClass

void initClass()

A stub func; do class-specific initialization in subclasses. See Widget for an example.

initData

void initData(atts)

This initializes data needed by JObject for bookkeeping.

processAtt

void processAtt(atts, name)

Performs the default processing on the atts parameter for the given attribute.

The default attribute processing to perform is to take the value indicated by the key, call .setAttribute(key, value), and delete the key out of the params object. (Thus, the atts object is consumed; be aware of this.)

For many initialization functions, it often becomes necessary to consume some attribute settings before the final .init call, because some of the attributes may affect the initialization itself (like what DOM nodes are constructed). This is in some sense bad form since it means those attributes must be set at construction and can't be reset later, but this is often easier and sometimes unavoidable. You can use this function to still tap into the full .setAttribute machinery safely, but not completely, depending on when you call this.

Be aware when you call this manually of where you are in the initialization sequence for your object and what may not be ready yet; for instance, if you call this before Widget.prototype.initDOM, the following will not have occurred:

• The .domNode will not have been created (unless you did it yourself), so DOM manipulation will not work.
• The Variables will not yet have been initialized (because in general they require the domNode), so .setAttribute and .getAttribute calls that "ought" to go through them will not. (You'll have to defer them.)<\li><\ul>

Parameters:
atts - The attributes object for this widget.
name - Either a string identifing a name of an attribute to pull out of the atts and call .setAttribute with, or a list of strings of such names. (i.e., either .processAtt(atts, "name") or .processAtt(atts, ["name", "value"]).) This function technically should have a name of indeterminate plurality, but English has no such thing.

name can safely point at something such that !(name in atts), but that probably indicates you need another .defaults entry; .setAttribute will be called with the undefined.

---

remoteExecute

void remoteExecute(url, postData, errorInCode, sync)

Execute a remote script in the context of this object.

This is the JObject "AJAX" support; it takes in a URL specification (probably relative) and optionally info to post, retrieves the resulting Javascript code, and executes it.

The XMLHttpRequest object is returned to you, so you can cancel the request if you want before it completes.

(Note: I am looking into how to add better error detection, which will likely change the function signiture in later versions. IE sometimes fails to make it to "readystate 4", and I have not yet dug in enough to know why that is.)

The resulting Javascript code will be executed in the context of this function, but since the eval is in a handler "this" will actually refer to the XMLHttpRequest object. The variable "obj" will be available which will refer to the JObject. The resulting API is simply "anything the object can do, the server can do". There is nothing particularly special about this code, so feel free to customize away on your own projects. (Consider this more a starter function than a real solution, which, in my experience, always ends up customized anyhow.)

Parameters:
url - The URL to read the code from; include querystring parameters here just as you'd see them in the browser if you like. Note the querystring, for reasons beyond my control, at least in Mozilla, is relative to the location of the jobject.js file, not the using page. You should probably use absolute URLs (starting from /), which you can construct with appropriate manipulations from window.location.
postData - The post data to send, if any. If this is blank, false, or undefined, the method used on the webserver will be "GET". If this is defined, the method used on the webserver will be "POST".
errorInCode - The code from the server will be run in a "try" block; this function should be a function which will recieve one parameter, the exception that resulted from executing the code from the server. Note this is distinct from an error in the retrieval of the page; currently you can not pass a handler for that.
sync - Run the remote exection synchronously. This is not useful for deployed code and probably isn't even very useful for debugging; this is for the test code and only needed then since Javascript has no threading model. Don't use this unless you really know what you are doing.

---

set

Object set()

Synonym for ".setAttribute".

---

setAttribute

void setAttribute(name, value, extra)

Sets the chosen attribute through the cascade lookup described in detail in the HTML documentation.

Summary: Looks for a property defined via "get_[name]" method, a DOMVariable, an inherited value, or an attribute on the Widget object.

Parameters:
name - The name of the attribute to be set.
value - The value to set. What can be legitimately used as a value depends on the chosen target.
extra - If setAttribute will end up calling a function, this can be used to send extra stuff to that function.

---

Overview  File   Class  Tree  Index  Help
PREV CLASS  NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

Documentation generated by JSDoc on Tue May 3 17:16:26 2005