Class Widget

Defined in widgets.js

Widget is the base class that XBLinJS is built on. It is too complicated to explain here; see the documentation .

Field Detail

content

Object content

Contains the content of the widget. See HTML documentation for details.

The default is a single span tag, but you should always override this; if you don't override it, that's a sign that class probably isn't really a Widget.

Widget

Widget()

Widget is the base class that implements all of the features of the framework. Future widgets should be derived from this class.

Parameters:
atts - The attribute object, if constructing a widget for actual use.
prototypeOnly - If true, this object is only being used for its prototype, so don't initialize it as if it is going to be on the screen.

appendChild

void appendChild(element, target)

Appends a DOM node, text fragment, or widget to the specified append target.

Parameters:
element - The DOM node, text fragment (as string) or widget to be appended.
target - The append target to add the element to. Defaults to the append target named "default".

appendTo

void appendTo(parent)

Appends this widget to some DOM node.

Parameters:
parent - The DOM node (or Widget) to append this Widget to.

checkObjectDef

void checkObjectDef(def)

A function to issue various warnings with the object specs as they occur.

For any given children specification, the output of this function will be constant, so you can leave this in while deploying.

This checks for the following common problems:

• <table>s must contain a <tbody> in IE when being created via DOM manipulation.
• Using class on an object def to specify a CSS class doesn't work all the time in all browsers; use className instead (analogous to the direct-access attribute), and XBLinJS will try to take care of the rest.

create

Object create(tagName, attDict, childText)

A convenience function for creating DOM elements, drawing on the XBLinJS flavor for the creation of the base widget.

This condenses five or more frequently-recurring lines down to a small handful, often just one, with much less redundancy.

Parameters:
tagName - The name of the tag to create.
attDict - A Javascript object that will be used to initialize the tag by calling .setAttribute(key, value) on every key and value in the given object.
childText - A convenience parameter that, if defined, will add the given childText to the node.

createObjectCustom

void createObjectCustom(objDef, child)

This method should be overridden to perform any custom object creation.

The default method throws an error on all input.

finishReplacementChildrenAdding

void finishReplacementChildrenAdding()

This method will be called when replaceElementWithWidget has finished adding any children there are for the tag.

This is only useful in the case where you are creating a widget that will primarily be invoked by tag. By default, it does nothing.

getGlobals

Object getGlobals()

Returns the relevant global storage for this widget.

This should be used in preference to directly accessing WidgetGlobals, so the widget is more likely to work in cross-frame situations.

hide

void hide()

Hides the widget.

Equivalent to this.domNode.style.display = "none".

init

void init(atts)

initDOM

void initDOM(atts)

This initializes the data storage and DOM nodes of the widget.

This is generally only overridden if you want to affect the DOM before setting values and stuff.

Parameters:
atts - The atts object containing the parameters, processed to include the defaults as needed.

initWidget

void initWidget(atts)

This should do any final initialization of the widget now that we have all the DOM nodes, such as setting up the value of those nodes and such.

The default implementation does nothing, just a stub to prevent this.initWidget is not a function errors.

prependChild

void prependChild(element, target)

Prepends a DOM node, text fragment, or Widget to the specified append target.

Parameters:
element - The DOM node, text fragment (as string), or Widget to be prepended.
target - The append target to add the element to, defaulting to "default".

registerEventHandler

Object registerEventHandler(eventType, handleMethod, target, context)

Registers an event handler.

Normally you should define the specially named methods to pick up events, but you can call this manually. This is necessary to attach to a foreign widget.

Parameters:
eventType - The type of the event to catch, stripped of the "on" prefix. e.g., "blur", "focus", "keypress".
handleMethod - The name of the method to be called as the handler. Will be passed a single parameter, the event object from Javascript. Note the word "method"; only Widgets can handle events. (This may change later if there is call for it.)
target - The name of the DOM node or widget to recieve the event from, as seen from the widget you are calling registerEventHandler from. For example, if you are trying to pick up a click on a button, pass in the name corresponding to that button. This, if false, defaults to the domNode of the widget; this will often be the case when calling it manually unless you are tightly binding the two Widgets together (generally bad). This must be a string, not a reference, which implies events can only be registered on things with names.

show

void show()

Shows the widget.

Equivalent to this.domNode.style.display = "". Widgets default to displaying just like anything else, of course, unless you do something.

Object toString()