Developer documentation

This section is organized into several areas:

  • Elements: web components which you can use directly in your web projects, or as starting points for your own components. These elements do their best to meet Gold Standard checklist for Web Components, a rigorous standard for ensuring a high level of component quality.

  • Mixins: aspects of component behavior that can be combined to create functional web components that meet the Gold Standard.

  • Helpers: low-level functions used by the above, and also avaible for cases where you need to build your own solution.

Elix render pipeline

Elix components use a functional-reactive programming (FRP) architecture. To achieve high quality, reliable behaviors across a large number of components, the project breaks down component behaviors in mixins. These mixins cooperate with each other, generally handling a specific point in a rendering pipeline:

events → methods → state → updates → DOM

  1. User activity generates DOM events, such as a keydown or touchstart event. User activity can also trigger application behavior that produces custom element lifecycle callbacks (e.g., attributeChangedCallback). These can also be considered events in this pipeline.
  2. Event handlers respond by invoking methods or setting properties on the component. (In very simple cases, an event handler skip this step, and directly call setState to update component state.)
  3. Component methods/properties in turn update component state. The method/property may call setState directly, or it might invoke another method/property that ultimately calls setState.
  4. The component is asked for updates it would like to apply to the DOM.
  5. Updates render changes to the DOM. Alternatively, the component can implement an internal render method that updates the DOM directly.

In rare cases, a component may need to do additional work after updates have been been rendered to the DOM.

Core mixins that define the pipeline

The pipeline described above is defined by a core set of component mixins:

  • ReactiveMixin. Manages a component's state property, and renders the compnent when state changes.
  • RenderUpdatesMixin. Helps a component map state to a set of updates that should be applied to DOM attributes, classes, styles, and properties.
  • ShadowTemplateMixin. Creates a component's shadow root and stamps a template into it.

For convenience, this set of core mixins is provided in a single base class called ElementBase. (ElementBase also includes AttributeMarshallingMixin, below.) When creating your own components, you don't have to use that base class; you can use the mixins above directly.

The remaining Elix mixins generally focus on the transition from one of these steps in the pipeline to the next.

Mixins that handle events (events → methods)

Some of these mixins directly update state.

Mixins that map methods to other methods

These mixins generally map from a low-level abstraction (e.g., a specific type of key has been pressed) to a higher-level abstraction (something should be selected).

Mixins that update state (methods → state)

  • OpenCloseMixin. Tracks the opened/closed state, providing open/close methods that set a state.opened member.
  • SelectedItemTextValueMixin. Supplies a value property that gets/sets the item specified by a selectedIndex property.
  • SingleSelectionMixin. Maps selection methods like selectPrevious/selectNext to changes in state.selectedIndex.

Mixin that render state (state → render)

  • AriaListMixin. Renders state.selectedIndex as various ARIA attributes like aria-activedescendant.
  • ArrowDirectionMixin. Renders left/right arrow buttons.
  • ContentItemsMixin. Defines an items property based on state.content, filtering out auxiliary invisible elements. During rendering, the component is given a chance to indicate what updates should be assigned to each specific item in items.
  • DialogModalityMixin. Renders a default ARIA role.
  • OverlayMixin. Renders an open state as changes to display and z-index to make an element appear on top.
  • PageDotsMixin. Renders a set of dots corresponding to items in a carousel.
  • RenderUpdatesMixin

Mixins that perform work after render

In rare cases, a mixin may need to perform work after a component has been rendered in the DOM.

Other resources

More information and background about the Elix project can be found at the following:

© 2016-2018 Component Kitchen Inc. and contributors to the Elix project. ELIX and the Elix project logo are registered or unregistered trademarks of Component Kitchen Inc. in the United States and/or other countries. Other trademarks are the property of their respective owners. Any use of such trademarks without written permission sought and obtained from Component Kitchen is prohibited.

The Elix project is administered, as a courtesy, by Component Kitchen for the benefit of the project’s contributors and the developer community as a whole.