polymer/src/mixins/element-mixin.html

<!--
@license
Copyright (c) 2014 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->

<link rel="import" href="../utils/boot.html">
<link rel="import" href="../utils/mixin.html">
<link rel="import" href="../utils/case-map.html">
<link rel="import" href="../utils/style-gather.html">
<link rel="import" href="../utils/resolve-url.html">
<link rel="import" href="../elements/dom-module.html">
<link rel="import" href="property-effects.html">

<script>
/**
 * Element class mixin that provides the core API for Polymer's meta-programming
 * features including template stamping, data-binding, attribute deserialization,
 * and property change observation.
 *
 * @polymerMixin
 * @mixes Polymer.PropertyEffects
 * @memberof Polymer
 */
Polymer.ElementMixin = Polymer.dedupingMixin(function(base) {

  const polymerElementBase = Polymer.PropertyEffects(base);

  let caseMap = Polymer.CaseMap;

  /**
   * Returns the `properties` object specifically on `klass`. Use for:
   * (1) super chain mixes togther to make `propertiesForClass` which is
   * then used to make `observedAttributes`.
   * (2) properties effects and observers are created from it at `finalize` time.
   * @param {HTMLElement} klass
   * @private
   */
  function ownPropertiesForClass(klass) {
    if (!klass.hasOwnProperty(
      goog.reflect.objectProperty('__ownProperties', klass))) {
      klass.__ownProperties =
        klass.hasOwnProperty(goog.reflect.objectProperty('properties', klass)) ?
        klass.properties : {};
    }
    return klass.__ownProperties;
  }

  /**
   * Returns the `observers` array specifically on `klass`. Use for
   * setting up observers.
   * @param {HTMLElement} klass
   * @private
   */
  function ownObserversForClass(klass) {
    if (!klass.hasOwnProperty(
      goog.reflect.objectProperty('__ownObservers', klass))) {
      klass.__ownObservers =
        klass.hasOwnProperty(goog.reflect.objectProperty('observers', klass)) ?
        klass.observers : [];
    }
    return klass.__ownObservers;
  }

  /**
   * Mixes `props` into `flattenedProps` but upgrades shorthand type
   * syntax to { type: Type}.
   * @param {Object} flattenedProps
   * @param {Object} props
   * @private
   */
  function flattenProperties(flattenedProps, props) {
    for (let p in props) {
      let o = props[p];
      if (typeof o == 'function') {
        o = { type: o };
      }
      flattenedProps[p] = o;
    }
    return flattenedProps;
  }

  /**
   * Returns a flattened list of properties mixed together from the chain of all
   * constructor's `config.properties`. This list is used to create
   * (1) observedAttributes,
   * (2) class property default values
   * @param {HTMLElement} klass
   * @private
   */
  function propertiesForClass(klass) {
    if (!klass.hasOwnProperty(
      goog.reflect.objectProperty('__classProperties', klass))) {
      klass.__classProperties =
      flattenProperties({}, ownPropertiesForClass(klass));
      let superCtor = Object.getPrototypeOf(klass.prototype).constructor;
      if (superCtor.prototype instanceof PolymerElement) {
        klass.__classProperties = Polymer.mixin(
          Object.create(propertiesForClass(superCtor)),
          klass.__classProperties);
      }
    }
    return klass.__classProperties;
  }

  /**
   * Returns a list of properties with default values.
   * This list is created as an optimization since it is a subset of
   * the list returned from `propertiesForClass`.
   * This list is used in `_initializeProperties` to set property defaults.
   * @param {HTMLElement} klass
   * @private
   */
  function propertyDefaultsForClass(klass) {
    if (!klass.hasOwnProperty(
      goog.reflect.objectProperty('__classPropertyDefaults', klass))) {
      this.__classPropertyDefaults = null;
      let props = propertiesForClass(klass);
      for (let p in props) {
        let info = props[p];
        if ('value' in info) {
          klass.__classPropertyDefaults = klass.__classPropertyDefaults || {};
          klass.__classPropertyDefaults[p] = info;
        }
      }
    }
    return klass.__classPropertyDefaults;
  }

  /**
   * Returns true if a `klass` has finalized. Called in `ElementClass.finalize()`
   * @param {HTMLElement} klass
   * @private
   */
  function hasClassFinalized(klass) {
    return klass.hasOwnProperty(goog.reflect.objectProperty('__finalized', klass));
  }

  /**
   * Called by `ElementClass.finalize()`. Ensures this `klass` and
   * *all superclasses* are finalized by traversing the prototype chain
   * and calling `klass.finalize()`.
   * @param {HTMLElement} klass
   * @private
   */
  function finalizeClassAndSuper(klass) {
    let proto = klass.prototype;
    let superCtor = Object.getPrototypeOf(proto).constructor;
    if (superCtor.prototype instanceof PolymerElement) {
      superCtor.finalize();
    }
    finalizeClass(klass);
  }

  /**
   * Configures a `klass` based on a staic `klass.config` object and
   * a `template`. This includes creating accessors and effects
   * for properties in `config` and the `template` as well as preparing the
   * `template` for stamping.
   */
  function finalizeClass(klass) {
    klass.__finalized = true;
    let proto = klass.prototype;
    if (klass.hasOwnProperty(
      goog.reflect.objectProperty('is', klass)) && klass.is) {
      Polymer.telemetry.register(proto);
    }
    let props = ownPropertiesForClass(klass);
    if (props) {
      finalizeProperties(proto, props);
    }
    let observers = ownObserversForClass(klass);
    if (observers) {
      finalizeObservers(proto, observers, props);
    }
    // note: create "working" template that is finalized at instance time
    let template = klass.template;
    if (template) {
      if (typeof template === 'string') {
        let t = document.createElement('template');
        t.innerHTML = template;
        template = t;
      } else {
        template = template.cloneNode(true);
      }
      proto._template = template;
    }
  }

  /**
   * Configures a `proto` based on a `properties` object.
   * Leverages `PropertyEffects` to create property accessors and effects
   * supporting, observers, reflecting to attributes, change notification,
   * computed properties, and read only properties.
   * @param {HTMLElement} proto
   * @param {Object} properties
   * @private
   */
  function finalizeProperties(proto, properties) {
    for (let p in properties) {
      createPropertyFromConfig(proto, p, properties[p], properties);
    }
  }

  /**
   * Configures a `proto` based on a `observers` array.
   * Leverages `PropertyEffects` to create observers.
   * @param {HTMLElement} proto
   * @param {Array} observers
   * @private
   */
  function finalizeObservers(proto, observers, dynamicProperties) {
    for (let i=0; i < observers.length; i++) {
      proto._createMethodObserver(observers[i], dynamicProperties);
    }
  }

  /**
   * Creates effects for a property.
   *
   * Note, once a property has been set to
   * `readOnly`, `computed`, `reflectToAttribute`, or `notify`
   * these values may not be changed. For example, a subclass cannot
   * alter these settings. However, additional `observers` may be added
   * by subclasses.
   *
   * @param {string} name Name of the property.
   * @param {*=} info Info object from which to create property effects.
   * Supported keys:
   *
   * * type: {function} type to which an attribute matching the property
   * is deserialized. Note the property is camel-cased from a dash-cased
   * attribute. For example, 'foo-bar' attribute is dersialized to a
   * property named 'fooBar'.
   *
   * * readOnly: {boolean} creates a readOnly property and
   * makes a private setter for the private of the form '_setFoo' for a
   * property 'foo',
   *
   * * computed: {string} creates a computed property. A computed property
   * also automatically is set to `readOnly: true`. The value is calculated
   * by running a method and arguments parsed from the given string. For
   * example 'compute(foo)' will compute a given property when the
   * 'foo' property changes by executing the 'compute' method. This method
   * must return the computed value.
   *
   * * reflectToAttriute: {boolean} If true, the property value is reflected
   * to an attribute of the same name. Note, the attribute is dash-cased
   * so a property named 'fooBar' is reflected as 'foo-bar'.
   *
   * * notify: {boolean} sends a non-bubbling notification event when
   * the property changes. For example, a property named 'foo' sends an
   * event named 'foo-changed' with `event.detail` set to the value of
   * the property.
   *
   * * observer: {string} name of a method that runs when the property
   * changes. The arguments of the method are (value, previousValue).
   *
   * @param {HTMLElement} proto
   * @param {string} name
   * @param {object} info
   * @param {object} props
   * @private
   */
  /* Note: Users may want control over modifying property
   effects via subclassing. For example, a user might want to make a
   reflectToAttribute property not do so in a subclass. We've chosen to
   disable this because it leads to additional complication.
   For example, a readOnly effect generates a special setter. If a subclass
   disables the effect, the setter would fail unexpectedly.
   Based on feedback, we may want to try to make effects more malleable
   and/or provide an advanced api for manipulating them.
   Also consider adding warnings when an effect cannot be changed.
  */
  function createPropertyFromConfig(proto, name, info, allProps) {
    // computed forces readOnly...
    if (info.computed) {
      info.readOnly = true;
    }
    // Note, since all computed properties are readOnly, this prevents
    // adding additional computed property effects (which leads to a confusing
    // setup where multiple triggers for setting a property)
    // While we do have `hasComputedEffect` this is set on the property's
    // dependencies rather than itself.
    if (info.computed  && !proto._hasReadOnlyEffect(name)) {
      proto._createComputedProperty(name, info.computed, allProps);
    }
    if (info.readOnly && !proto._hasReadOnlyEffect(name)) {
      proto._createReadOnlyProperty(name, !info.computed);
    }
    if (info.reflectToAttribute && !proto._hasReflectEffect(name)) {
      proto._createReflectedProperty(name);
    }
    if (info.notify && !proto._hasNotifyEffect(name)) {
      proto._createNotifyingProperty(name);
    }
    // always add observer
    if (info.observer) {
      proto._createPropertyObserver(name, info.observer, allProps[info.observer]);
    }
  }

  /**
   * Configures an element `proto` to function with a given `template`.
   * The element name `is` and extends `ext` must be specified for ShadyCSS
   * style scoping.
   * @param {HTMLElement} proto
   * @param {HTMLTemplateElement} template
   * @param {string} is
   * @param {string} ext
   * @private
   */
  function finalizeTemplate(proto, template, is, ext) {
    // support `include="module-name"`
    let cssText = Polymer.StyleGather.cssFromTemplate(template) +
      Polymer.StyleGather.cssFromModuleImports(is);
    if (cssText) {
      let style = document.createElement('style');
      style.textContent = cssText;
      template.content.insertBefore(style, template.content.firstChild);
    }
    if (window.ShadyCSS) {
      window.ShadyCSS.prepareTemplate(template, is, ext);
    }
    proto._bindTemplate(template, propertiesForClass(proto.constructor));
  }

  /**
   * @polymerMixinClass
   * @unrestricted
   */
  class PolymerElement extends polymerElementBase {

    static get observedAttributes() {
      if (!this.hasOwnProperty(goog.reflect.objectProperty('__observedAttributes', this))) {
        let list = [];
        let properties = propertiesForClass(this);
        for (let prop in properties) {
          list.push(Polymer.CaseMap.camelToDashCase(prop));
        }
        this.__observedAttributes = list;
      }
      return this.__observedAttributes;
    }

    /**
     * Called automatically when the first element instance is created to
     * ensure that class finalization work has been completed.
     * May be called by users to eagerly perform class finalization work
     * prior to the creation of the first element instance.
     * @public
     */
    static finalize() {
      if (!hasClassFinalized(this)) {
        finalizeClassAndSuper(this);
      }
    }

    static get template() {
      if (!this.hasOwnProperty(goog.reflect.objectProperty('_template', this))) {
        this._template = Polymer.DomModule.import(this.is, 'template') ||
          // note: implemented so a subclass can retrieve the super
          // template; call the super impl this way so that `this` points
          // to the superclass.
          Object.getPrototypeOf(this.prototype).constructor.template;
      }
      return this._template;
    }

    constructor() {
      super();
      Polymer.telemetry.instanceCount++;
      // Stamp template
      if (this._template) {
        this.root = this._stampTemplate(this._template);
      } else {
        this.root = this;
      }
    }

    _initializeProperties() {
      this.constructor.finalize();
      // note: finalize template when we have access to `localName` to
      // avoid dependence on `is` for polyfilling styling.
      if (this._template && !this._template.__polymerFinalized) {
        this._template.__polymerFinalized = true;
        finalizeTemplate(this.__proto__, this._template, this.localName);
      }
      super._initializeProperties();
      // apply property defaults...
      let p$ = propertyDefaultsForClass(this.constructor);
      if (!p$) {
        return;
      }
      for (let p in p$) {
        let info = p$[p];
        if (!this._isPropertyPending(p)) {
          var value = typeof info.value == 'function' ?
            info.value.call(this) :
            info.value;
          if (this._hasPropertyEffect(p)) {
            this._setProperty(p, value)
          } else {
            this[p] = value;
          }
        }
      }
    }

    connectedCallback() {
      if (window.ShadyCSS) {
        window.ShadyCSS.styleElement(this);
      }
      this._flushProperties();
    }

    disconnectedCallback() {}

    ready() {
      super.ready();
      if (this._template) {
        this.root = this._attachDom(this.root);
      }
    }

    /**
     * Attach an element's stamped dom to itself. By default,
     * this method creates a `shadowRoot` and adds the dom to it.
     * However, this method may be overridden to allow an element
     * to put its dom in another location.
     *
     * @method _attachDom
     * @throws {Error}
     * @suppress {missingReturn}
     * @param {NodeList} dom to attach to the element.
     * @return {Node} node to which the dom has been attached.
     */
    _attachDom(dom) {
      if (this.attachShadow) {
        if (dom) {
          if (!this.shadowRoot) {
            this.attachShadow({mode: 'open'});
          }
          this.shadowRoot.appendChild(dom);
          return this.shadowRoot;
        }
      } else {
        throw new Error('ShadowDOM not available. ' +
          // TODO(sorvell): move to compile-time conditional when supported
         'Polymer.Element can create dom as children instead of in ' +
         'ShadowDOM by setting `this.root = this;\` before \`ready\`.');
      }
    }

    attributeChangedCallback(name, old, value) {
      if (old !== value) {
        let property = caseMap.dashToCamelCase(name);
        let type = propertiesForClass(this.constructor)[property].type;
        if (!this._hasReadOnlyEffect(property)) {
          this._attributeToProperty(name, value, type);
        }
      }
    }

    /**
     * Update styling for this element
     *
     * @param {Object=} properties
     *  Override styling with an object of properties where the keys are css properties, and the values are strings
     *  Example: `this.updateStyles({'color': 'blue'})`
     *  These properties are retained unless a value of `null` is set.
     */
    updateStyles(properties) {
      if (window.ShadyCSS) {
        window.ShadyCSS.styleSubtree(this, properties);
      }
    }

    /**
     * Rewrites a given URL relative to the original location of the document
     * containing the `dom-module` for this element.  This method will return
     * the same URL before and after vulcanization.
     *
     * @method resolveUrl
     * @param {string} url URL to resolve.
     * @return {string} Rewritten URL relative to the import
     */
    resolveUrl(url) {
      const module = Polymer.DomModule.import(this.constructor.is);
      const root = module ? module.assetpath : document.baseURI;
      return Polymer.ResolveUrl.resolveUrl(url, root);
    }

  }

  return PolymerElement;
});

// telemetry
Polymer.telemetry = {
  instanceCount: 0,
  registrations: [],
  _regLog: function(prototype) {
    console.log('[' + prototype.is + ']: registered')
  },
  register: function(prototype) {
    this.registrations.push(prototype);
    Polymer.log && this._regLog(prototype);
  },
  dumpRegistrations: function() {
    this.registrations.forEach(this._regLog);
  }
};

Polymer.updateStyles = function(props) {
  if (window.ShadyCSS) {
    window.ShadyCSS.styleDocument(props);
  }
};
</script>