Components

BaseComponent

class BaseComponent()

Component base class for all AWML components.

BaseComponent.debug

type: boolean

If true, this component will output warnings and log messages to the developer console. Useful for debugging. This property is available as the debug attribute.

PrefixComponentBase

class PrefixComponentBase()

Base class for components which can bind to backend values using an address.

PrefixComponentBase.src

type: string

The source address of the backend value to bind to this property. The source address is combined with prefix attributes on this component and all it’s DOM parents into the final address. This property can be set using the src attribute.

PrefixComponentBase.srcPrefix

type: string

The source address prefix to use for the src property in this component. If null, the default prefix will be used, which corresponds to the prefix attribute. If not null, the source address will instead be constructed using the prefix-<srcPrefix> attribute. This feature can be used to connect bind components to different backend parameter trees. This property can be set using the src-prefix atttribute.

PrefixComponentBase.transformReceive

type: function

Transformation function for receiving backend values. This function is called in the context of this component for every value received from the backend. This property can also be set using the transform-receive attribute.

PrefixComponentBase.transformSend

type: function

Transformation function for backend values. This function is called in the context of this component for every value sent to the backend. This property can also be set using the transform-send attribute.

PrefixComponentBase.transformSrc

type: function

Transformation function for the source address. This function is called in the context of this component once before a source address is subscribed to. This property can also be set using the transform-src attribute.

PrefixComponentBase.debounce

type: number

Number of milliseconds to debounce incoming values. This currently only works with ListValue sources. This property can also be set using the debounce attribute.

PrefixComponentBase.partial

type: boolean

If true, partial values are received from a ListValue source. This property can also be set using the partial attribute.

PrefixComponentBase.pipe

A function which is called before subscribing to a DynamicValue. It can be used to transform the DynamicValue, e.g. by using an operator. If null, no transformation happens. This propert can also be set using the pipe attribute. See DynamicValue Operators for a list of supported operators.

PrefixComponentBase.replay

type: boolean

Determines the value of the second argument to subscribe() on the backend value. If false, the current cached value will not be emitted. This property can also be set using the no-replay attribute. Defaults to true.

AttributesComponent

The <awml-attribute> component can be used to attach a backend parameter to attributes on a DOM element. It inherits all properties and attributes from PrefixComponentBase.

Note that <awml-attribute> should not be used to set the prefix attributes, use <awml-prefix>, instead.

Example:

<div>
  <awml-attributes
    src='/label'
    transform-receive='(label) => { title: label }'>
  </awml-attributes>
</div>
class AttributesComponent()

Component which modifies the attributes of its parent element. The data is expected to be an object containing the attributes.

This component has the following properties (and corresponding attributes):

StylesComponentBase.triggerResize

type: boolean

If true, a resize is triggered after updating the display state. This property can be set using the trigger-resize attribute.

BackendComponent

class BackendComponent()

This component can be used to instantiate backends and register them under a name.

This component has the following properties (and corresponding attributes):

BackendComponent.type

The backend type. Check the backends/ directory for different backend types.

BackendComponent.name

The backend name.

BackendComponent.retryInterval

The starting retry interval for reconnects. The actual retry interval will increase with each failed reconnection attempt.

BackendComponent.isOpen

Returns true is the backend is open.

BackendComponent.backend

Returns the current backend object. If the backend does not exist or is not in open state, null will be returned.

BackendComponent.whenOpen()

Returns a promise that resolves when the backend is in open state.

BindComponent

class BindComponent()

BindComponent can be used to create a series of bindings between backend values and a its parent component. This component is a lightweight alternative for situations where many bindings are created on the same component.

This component has the following properties (and corresponding attributes):

BindComponent.bindings

type: Array.<IBindingDescription>

A list of binding descriptions.

ClassComponent

The <awml-class> component can be used to set CSS classes on a DOM element based on the value of a backend parameter. It inherits all properties and attributes from PrefixComponentBase.

Example:

<div>
  <awml-class
    src='/Mute'
    transform-receive='(muted) => muted ? "is-muted" : null'>
  </awml-class>
</div>
class ClassComponent()

Component which modifies the CSS class of its parent element. The data can be either a string or an array of strings.

This component has the following properties (and corresponding attributes):

CloneComponent

class CloneComponent()

The AWML-CLONE component loads and clones templates. It can be combined with data bindings to dynamically load, modify and clone templates.

This component has the following properties (and corresponding attributes):

CloneComponent.template

Identifier of the template to be loaded and cloned. If fetch is false, this is interpreted as a DOM id of a TEMPLATE node or, if fetch is true, as a relative URL.

CloneComponent.fetch

If true, the template identifier (e.g. either the template property or the vaule received by a binding) will be interpreted as a relative URL. The template will then be fetched. Relative URLs are interpreted relative to the current template location.

CloneComponent.notemplate

If true, the src property will be ignored and no template will be loaded. Instead, an empty DocumentFragment will be generated. This is useful together with transformTemplate in order to generate templates dynamically.

CloneComponent.nocache

If true, templates will not be cached.

CloneComponent.transformTemplate

type: function

An optional callback which is called before a template is cloned. It can be used to transform the template DOM.

CloneComponent.triggerResize

If not false, a resize is triggered in the parent widget when the template has been loaded. If it is a positive integer N, a resize will be triggered N levels higher in the widget tree.

The default value is 0.

This property can be set using the trigger-resize attribute.

CloneComponent.importScripts

If true, SCRIPT tags are extracted from templates and placed into the page HEAD.

CloneComponent.waitForLoad()

Wait for the template to be loaded.

EventComponent

class EventComponent()

The AWML-EVENT component can be used to attach event handlers to an AUX widget or other DOM nodes.

If the parent is an AUX widget the event handler will use the AUX widget event mechanism, is the parent is any other DOM node, the standard DOM event API will be used.

This component has the following properties (and corresponding attributes):

OptionComponent

The OptionComponent can be used to create two-way bindings with a parent component. Custom binding types can be implemented to extend its functionality.

class OptionComponent()

The AWML-OPTION component can be used to bind to options in AUX widgets. The type and behavior of the binding depends on the specific option being used. Standard option types available as part of AWML are

  • static for setting options to static values (see StaticOption),

  • media for setting options based on CSS media queries and

  • bind for binding options to backend values (see BindOption).

Note that each option has additional attributes which can be used to control its behavior. They are documented for each option type. These additional options are only interpreted when the option is first connected. This means that when these options are changed dynamically, it is necessary to also modify either name or type to trigger the option to be reinitialized.

This component has the following properties (and corresponding attributes):

OptionComponent.type

Type of this option.

OptionComponent.name

Option name in the parent widget.

PrefixComponent

class PrefixComponent()

Component which modifies the prefix of its parent element. The data can be either a string or null. The handle attribute can be used to control which src-prefix this should apply to.

This component has the following properties (and corresponding attributes):

PrefixComponent.handle

type: string

The source handle to use. Passed as second argument to setPrefix().

StylesComponent

class StylesComponent()

Component which modifies the styles of its parent element. The data is expected to be an object containing the styles.

This component has the following properties (and corresponding attributes):

TemplateComponent

TemplateComponent is a baseclass for building powerful custom components. See Template Components for an introduction.

class TemplateComponent()

TemplateComponent is a base class for components using DOM templates.

TemplateComponent.fromString(input)

Creates a component class from a template string.

Arguments

  • input (string|object) – The template string.

Returns

class – A subclass of TemplateComponent which - when instantiated - will clone the template.

TemplateComponent.create(options)

Creates a template component from a set of options.

Arguments

  • options (object) –

  • options.template (string|DOMTemplate) – The template.

  • options.properties (Array.<string>) – An optional list of property names. They are added to the list of properties referenced from the template itself.

  • options.ignoreProperties (Array.<string>) – An optional list of property names which should not automatically create dynamic properties.

Returns

class – A subclass of TemplateComponent which - when instantiated - will clone the template.

TemplateComponent.awmlCreateBinding(name, options)

Internal method called when a binding is created. This is used by BindOption to create binding with template components.

Arguments

  • name (string) – The binding name.

  • options (Object) – The binding options. See bindingFromComponent for option values.

Returns

DynamicValue – Returns a dynamic value which represents the given binding.

TemplateComponent.whenAttached()

Returns a promise which resolves when the DOM template has been attached.

Returns

Promise –

TemplateComponent.triggerUpdate(propertyName)

Mark a certain property as changed and (if necessary) trigger redraw() to be called in the next rendering frame.

Arguments

  • propertyName (string) – The name of the property which changed.

TemplateComponent.redraw()

Called in a rendering frame and updates the DOM.

ShowComponent

class ShowComponent()

The AWML-SHOW component makes its parent widget visible if the corresponding backend value is true.

This component has the following properties (and corresponding attributes):