Element

Element

Elements represent the adaptation of the HTML Document Object Model to Croquet. While the basic API is modeled after the DOM spec, it has Croquet-specific features. On the other hand, it omits some types of elements in the standard.

Elements are created and appended to the "top" element to form a tree. For each Element model object, a corresponding ElementView object is created. Each ElementView object instantiates the corresponding native DOM element. When some code updates a property on an Element model, the framework applies the change to the native DOM element. The View side code can manipulate the View object as well as the native DOM element.

A virtual DOM element holds its parent element (parentNode), the list of children (childNodes), the dictionary of style properties (style), its DOM ID (renamed to domId to avoid name conflict with Croquet model id), CSS class list (classList), and the static part of the sub-element in HTML form (innerHTML).

It also stores a set of expander code blocks for the model side of the Element, and another set for its View counterpart. An Element also contains a string representation of its CSS class definitions.

A subset of the commonly used DOM API is implemented for Element. For instance, methods such as appendChild() and removeChild() can be used to set up the display scene.

The set of expanders for Element (code) or ElementView (viewCode) are converted to an executable form. Typically an expander has an API call to add an event listener (addEventListener()) or a Croquet event subscription (subscribe()) to trigger a method in it.

Element has several subclasses for custom DOM element types. There are subclasses for iframe, canvas, video, img, and textarea. The first four are relatively simple wrappers to handle specific features. The textarea creates a multi-user collaborative text editor. Other element types (such as ul, select, h1, etc.) are not included, as a div element with style and event handlers can mimic them. But when the need arises, we could add them to the framework.

Members

(readonly) style :Style

The virtualized CSSStyleDeclaration object for the receiver. It has setProperty() getPropertyValue(), and removeProperty() (a subset of the spec described in CSSStyleDeclaration).

Type:
  • Style

(readonly) classList :ClassList

The classList of the receiver. The classList object has add(), remove(), replace(), and contains() (a subset of the spec described in classList).

Type:
  • ClassList

domId :string|undefined

Element's DOM ID.

Type:
  • string | undefined

Methods

appendChild(elem)

Add a child Element to the end of an Element's childNodes list.

Parameters:
Name Type Description
elem Element | ElementRef

the child element to be added

Example:
let another = this.createElement("div"); this.appendChild(another);

insertBefore(elem, referenceElemopt)

Add a child Element in front of referenceElem in the childNodes list. If referenceElem is null, the element is added at the end of the list.

Parameters:
Name Type Attributes Description
elem Element | ElementRef

the child element to be added

referenceElem Element | ElementRef <optional>

the child element to be added

Example:
let anchor = this.querySelector("#myElem"); this.insertBefore(another, anchor);

remove()

Remove the receiver from its parent's childNodes. If the receiver is not in the display scene, this method does not have any effect.

Example:
another.remove();

removeChild(elemopt)

Remove the specified Element from the receiver's childNodes.

Parameters:
Name Type Attributes Description
elem Element | ElementRef <optional>

the child element to be removed

Example:
this.removeChild(another);

addEventListener(eventType, methodName, useCaptureopt)

Add a listener for a DOM event specified by eventType to the receiver. This resembles the native DOM's addEventListener, but the second argument is restricted to a string that specifies the name of a method, to conform to Croquet's Model. A typical case is to call addEventListener() from an expander. In that case, the method is looked up from the calling expander.

Parameters:
Name Type Attributes Description
eventType string

the DOM event type

methodName string

the name of the handler in the calling expander

useCapture boolean <optional>

indicating if the event will be dispatched to elements below

Example:
this.addEventListener("click", "onClick"); // onClick is the name of a method

removeEventListener(eventType, methodName)

Remove the specified event listener from the Element.

Parameters:
Name Type Description
eventType string

the DOM event type

methodName string

the name of the handler in the calling expander

Example:
this.removeEventListener("click", "onClick");

querySelector(query) → {Element|null}

Look up an Element that matches the specified query. This is similar to https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector but, as of writing, it only works with the #id form.

Parameters:
Name Type Description
query string

# followed by a domId

Returns:

the Element found, or null.

Type
Element | null
Example:
let elem = this.querySelector("#myElement");

createElement(elementType) → {Element}

Create a virtual DOM Element of type specified by elementType. It is similar to the native DOM API, which uses the global document.createElement (https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement). elementType is one of "div", "canvas", "textarea", "iframe", "video", or "img".

Parameters:
Name Type Description
elementType string

the type element to instantiate

Returns:

An instance or sub-instance of Element

Type
Element
Example:
let elem = this.createElement("canvas");

setCode(code)

Set the receiver's list of expanders (on the model side). The argument can be either a string specifying a single expander, or an array of strings to specify multiple expanders. If a string has the dot-delimited form libraryName.expanderName, the expander code is looked up from the "library" of the receiver. Alternatively, a string can contain a full expander definition starting with the keyword class. The first form is provided to save space when there are many instances of Element that share the same expander.

Parameters:
Name Type Description
code string | Array.<string>

singleton code (a string) or an array of strings that specify expanders

Examples:
this.setCode("myLib.MyExpander");
this.setCode("class C {onClick {this.remove();}}");
this.setCode(["myLib.MyExpander", "myLib.YourExpander"]);

addCode(code)

Add a list of expanders to the receiver. The difference from setCode() is that setCode() removes all existing expanders while addCode() doesn't.

Parameters:
Name Type Description
code string | Array.<string>

singleton code (a string) or an array of strings that specify expanders

Example:
this.addCode("myLib.MyExpander");

getCode() → {string|Array.<string>}

Return the list of expanders.

Returns:
  • singleton code (a string) or an array of strings that specify expanders
Type
string | Array.<string>

setViewCode(code)

Set the list of expanders for the receiver's View. The argument can be either a string specifying a single expander, or an array of strings to specify multiple expanders.

Parameters:
Name Type Description
code string | Array.<string>

singleton code (a string) or an array of strings that specify expanders

Examples:
this.setViewCode("myLib.MyExpander");
this.setViewCode("class C {onClick {this.remove();}}");
this.setViewCode(["myLib.MyExpander", "myLib.YourExpander"]);

addViewCode(code)

Add a list of expanders to the receiver's View. The difference from setViewCode() is that setViewCode() removes all existing expanders while addViewCode() doesn't.

Parameters:
Name Type Description
code string | Array.<string>

singleton code (a string) or an array of strings that specify expanders

Example:
this.addViewCode("myLib.MyExpander");

getViewCode() → {string|Array.<string>}

Return the list of expanders for the view

Returns:
  • singleton code (a string) or an array of strings that specifies expanders
Type
string | Array.<string>

setStyleClasses(style)

The style string is stored in the Element, and added to the native display scene as a <style> node. Note that it is in the global scope so the CSS selectors may be picked up by other elements.

Parameters:
Name Type Description
style string

CSS classes to be included in the document

Example:
this.setStyleClasses(`.foo {background-color: black}`);

addStyleClasses(style)

Append the style to the existing styleClasses string.

Parameters:
Name Type Description
style string

CSS classes to be included in the document

Example:
this.addStyleClasses(`.bar {width: 10px}`);

getLibrary(path) → {string|class|null}

Returns the content in the Library mechanism. Typically a Library for an app is set up at the app's load time. The path is in the form libraryName.item, and the value of the specified item is returned. The return value is either a function or expander as a string, or an actual class object if specified item is in the classes array of the library.

Parameters:
Name Type Description
path string

dot-delimited path to the library in the Element and its ancestors

Returns:
Type
string | class | null
Example:
this.getLibrary("myLib.MyClass");

_set(name, value)

Store a value in the property dictionary for the receiver Element. NB: The underscore in the method name is a reminder that the value has to be a data structure that the Croquet serializer can serialize.

Parameters:
Name Type Description
name string

name of the property

value any

the new value of the property. It must be serializable by the Croquet Serializer.

Example:
this._set("myData", new Map());

_get(name) → {any}

Retrieve the value for name in the Element's property dictionary.

Parameters:
Name Type Description
name string

name of the property

Returns:

The value of the property.

Type
any
Example:
this._get("myData");

_delete(name)

Delete the entry from the Element's property dictionary.

Parameters:
Name Type Description
name string

name of the property to be deleted

Example:
this._delete("myData");

subscribe(scope, eventName, methodName)

Subscribe to a Croquet message specified by scope and eventName. The method specified by the methodName is invoked when the Croquet message is delivered to the model. Scope and eventName can be arbitrary strings. A common practice is to use the model ID (not to be confused with domId) as the scope to indicate that a message is related to a given Element, and eventName to specify the message's purpose.

Parameters:
Name Type Description
scope string

Croquet message scope

eventName string

Croquet message event name

methodName string

name of the expander method to invoke

Example:
this.subscribe(this.id, "myMessage", "myMessageHandler");

publish(scope, eventName, data)

Send a Croquet message with scope and eventName, with data as payload.

Parameters:
Name Type Description
scope string

Croquet message scope

eventName string

Croquet message event name

data any

a serializable value

Example:
this.publish(this.id, "myMessage", {a: 1, b: 2});

call(expanderName, methodName) → {any}

Invoke a method in the receiver's specified expander, with arguments. An error will be thrown if the receiver has no expander of that name, or the expander does not include that method. There is no need to use this form if the method is invoked from the same expander. In some cases, however, it is desirable to be able to invoke a method from a different expander, or a method of a different receiver.

Parameters:
Name Type Description
expanderName string

name of the expander

methodName string

name of the method

...arguments any

arguments for the method

Returns:

the return value from the method

Type
any
Example:
other.call("OtherExpander", "myMethod", 1, 2, 3);