polymer-2-decorators

Polymer 2 Decorators

Decorators can be used to describe element properties, observers, etc.

@customElement(tagName)

Sets the tag name of the custom element. The decorator is applied to the class. Tag names must include a - as per WebComponents specs.

Example of a <my-element>:

@customElement('my-element')
class MyElement extends Polymer.Element {

}

@property(propertyConfig)

Creates a Polymer property. It can be applied to a static class properties only.

The parameter propertyConfig is a map object that sets the options for the property:

{
    type?: enum;                     // Boolean, Date, Number, String, Array or Object
    reflectToAttribute?: boolean;    // should the property reflect to attribute
    readonly?: boolean;              // marks property as read-only
    notify?: boolean;                // if set to true, will trigger "propname-changed"
    computed?: string;               // computed function name (as string)
}

Examples:

@property
static foo;

// type: is specified for property deserialization.
// Used when it is passed to another elements in html attribute
@property({type: Number})
static initialValue = 42;

@property({readonly: true, computed: '_computeValue(foo, initialValue)'})
static computedReadOnlyValue = 0;

_computeValue(foo, initialValue) {
  return foo.toString() + initialValue;
}

@computed(propList, computedFn)

Makes a property computed. It can be applied to a static class properties only.

@property
static one = 'one';

@property
static two = 'two';

@property
@computed('one, two', (one, two) => one + two)
static three;

@observe(propList)

Sets an observer function for a single property or a list of properties.

If observing a single property, the function should be of the type function(newValue, oldValue).

If observing multiple properties (comma separated), the function receives only the new values, in the same order of the list.

// single property observer
@observe('name')
nameChanged(newName, oldName) {
   // ...
}

// multiple property observer
@observe('firstname, lastname')
fullnameChanged(newFirstName, newLastName) {
   // ...
}

@observeOnValue(prop)

Same as @observe decorator, but the function is called when the newValue is not null or undefined.

Only single property can be observed.

@observeSinceValue(prop)

Same as @observe decorator, but the function is called on the next change, since property was initialized with any value (oldValue !== undefined).

Only single property can be observed.

@eventListener(eventType, options)

Sets an event listener for the element and binds it to a function. Options — addEventListener options.

@eventListener('click')
onClick(e) {
   e.stopPropagation();
}

@statePath(statePath)

Use with polymer-redux

Assigns a Polymer property to reflect the Redux app state.

  @property
  @statePath('objects.total')
  static totalItems;

@routerStateParameter(stateParameter, options)

Use with polymer-2-ui-router

Assigns a Polymer property to reflect current ui-router state parameter.

The parameter options is a map object that sets the options for the property:

{
    reflectToState?: boolean;    // should the property be reflected back to state on change
}

  @property
  @routerStateParameter('page')
  static currentPage;