README.md

Demo and API docs

PropertiesFromAncestorBehavior

A Polymer Behavior for a web component to take a property value from the closest ancestor that has it. Supports change events.

Where it might be a good idea?

It can be useful for ubiquitous properties (think language of the UI, currency, disabled state to every input of a form, etc.) which would otherwise pollute attributes of every component with same boilerplate expression, or force usage of a global variable (usually without binding to changes).
An extra feature of being able to observe attributes helps with achieving easy-to-use web components, reusable in other app frameworks or pure HTML.

Usage:

Technically, it's a behavior factory function. To have a behavior instance created, you call the PropertiesFromAncestorBehavior().

class MyComponent extends Polymer.mixinBehaviors([
    PropertiesFromAncestorBehavior({
            // Just declaring a property here is enough to make it work.
            myProp1: {
                // Optionally, you can provide a default. If no ancestor is found, `defaultValue` will be used:
                defaultValue: 123, // (don't use the polymer's 'value:' for this though, because it may cause double initialization - once with such value, once with the value from ancestor (if they're different). That's because we can only reach the ancestor on 'attached', which happens after defaults get applied.

                // See "API Reference - Per-Property settings" for all available options

                // If you don't care about polylint, you can avoid repetition and just put here all other property settings. They get passed to declaration of this property on the element:
                notify: true,
                observer: '_myProp1Changed',
            },
        }) ], Polymer.Element)
{
    static get is() { return "my-component"; }
    static get properties() {
        return {
            // But if you want to keep polylint happy, you need to list the property here too:
            myProp1: {
                // Custom settings still work:
                notify: true,
                observer: '_myProp1Changed',
                // But you don't want to use 'value:' here but rather 'defaultValue:' above. See comment there for 'why'.
            }
        };
    }
}

the above declaration will make the properties available in <my-component>s template:

<template>
    myProp1 value is {{myProp1}}
    <br/>
    myProp2 value is {{myProp2}}
</template>

while their values will come from the closest ancestor that has the corresponding dash-case attribute.

<example-container-component my-prop1="some value" my-prop2="some other value"><!-- Container can also be a simple HTML <div>. As long as it has the attributes. These attributes are a requirement to discover the ancestor. If the element also has matching properties, they instead will be taken and their changes listened to. -->
  <my-component></my-component>
</example-container-component>

API Reference - Per-Property settings

These parameters can be specified for each property:

• defaultValue (Optional)
  If no ancestor is found, defaultValue will be used.
• ancestorMatches (Optional) of type HTML Selector
  • Instead of looking for ancestor with the dash-case attribute, you can provide a selector. This especially is needed for boolean attributes that start with 'false', because it's represented as no attribute at all. Example: ancestorMatches: '.ancestor-markup-class' - will listen to the closest ancestor with class="ancestor-markup-class"
• ancestorObservedItem (Optional)
  of enum type
  PropertiesFromAncestorBehavior.ObservedItem.PROPERTY_CHANGED_EVENT (default)
  PropertiesFromAncestorBehavior.ObservedItem.ATTRIBUTE
  If the ancestor doesn't emit *-changed events, you can use ATTRIBUTE to tell the behavior that it should use a MutationObserver to listen to the attribute.
  Take note that in this case the handlers will not fire in the same thread as the change, so if you need to schedule some work after the handlers, you will need to use setTimeout(..., 0).
• ancestorPropertyAlias (Optional)
  If the name of the property is different on the ancestor, specify it here (specify 'camelCase' name, but this will also change the expected dash-case attribute and '*-changed' event names).

HOW-TO: Automatically reflect container's lang attribute in your multi-language component

The HTML lang attribute is a standard way to declare the content language. It's useful for applying [lang=...] CSS rules and is recommended for future applications. It's then a perfect candidate to specify the language in one place and have your components automatically display the right contents:

<html lang="en">
  ...
  <p>
    <some-web-component>
      <span>
        <another-web-component></another-web-component>
      <span>
    </some-web-component>
  </p>
  ...
</html>

to achieve this effect with the Polymer's AppLocalizeBehavior, all you need to do is add our behavior next to it, with the following declaration:

...
class ... extends ...
    Polymer.AppLocalizeBehavior,
    PropertiesFromAncestorBehavior({
            language: {
                // This is needed because `AppLocalizeBehavior` requires `language` for the name - see also https://github.com/PolymerElements/app-localize-behavior/issues/98
                ancestorPropertyAlias: 'lang',
                // Observing the attribute will allow changing the language and seeing immediate effect:
                ancestorObservedItem: PropertiesFromAncestorBehavior.ObservedItem.ATTRIBUTE,
            },
        }),
...

HOW-TO: Native-like support for <fieldset disabled>

The native HTML form input elements like <input>, <button>, <select> elements don't require you to pass the disabled attribute to each usage. You use the ancestor fieldset disabled feature to disable all of the containing inputs.

Here's how this behavior can be used to support the same feature when your web component isn't built from these native inputs:

<template>
    <span on-tap="{{handleTap}}">Something only clickable when enabled</span>
</template>
...
class ... extends ...
    PropertiesFromAncestorBehavior({
            disabled: {
                // Use 'ancestorMatches' to provide a way to match while it's enabled (has no disabled attribute)
                ancestorMatches: 'fieldset',

                // <fieldset> has a disabled property, but changing it doesn't emit 'disabled-changed' event, so we must observe the attribute:
                ancestorObservedItem: PropertiesFromAncestorBehavior.ObservedItem.ATTRIBUTE,

                // Specify type, to properly get empty 'disabled' attribute deserialized into 'true':
                type: Boolean,
            },
        })
    ...
{
    ...
    handleTap() {
        if (this.disabled) return;
    
        // If we got here, we're enabled. Handle legitimate click:
        this.DoSomething();
    }
}