+
+ | Callback |
+ Description |
+
+
+ created |
+ Called when the element has been created, but before property values are
+ set and local DOM is initialized.
+ Use for one-time set-up before property values are set.
+
+ Use instead of createdCallback.
+
+ |
+
+
+ ready |
+ Called after property values are set and local DOM is initialized.
+ Use for one-time configuration of your component after local
+ DOM is initialized. (For configuration based on property values, it
+ may be preferable to use an observer.)
+
+ |
+
+
+ attached |
+ Called after the element is attached to the document.
+ Uses include accessing computed style information, and adding
+ document-level event listeners. (If you use declarative
+ event handling, such as annotated
+ event listeners or the
+ listeners object,
+ {{site.project_title}} automatically adds listeners on attach and removes
+ them on detach.)
+
+ Use instead of attachedCallback.
+
+ |
+
+
+ detached |
+ Called after the element is attached to the document.
+ Uses include removing event listeners added in attached.
+
+ Use instead of detachedCallback.
+
+ |
+
+
+ attributeChanged |
+ Called when one of the element's attributes is changed.
+ Use to handle attribute changes that don't correspond to
+ declared properties. (For declared properties, {{site.project_title}}
+ handles attribute changes automatically as described in
+ attribute deserialization.)
+
+ Use instead of attributeChangedCallback.
+
+ |
+
+
+
Example:
@@ -199,6 +257,10 @@ Example:
console.log(this.localName + '#' + this.id + ' was created');
},
+ ready: function() {
+ console.log(this.localName + '#' + this.id + ' has local DOM initialized');
+ },
+
attached: function() {
console.log(this.localName + '#' + this.id + ' was attached');
},
@@ -214,14 +276,28 @@ Example:
});
+
+
### Ready callback and local DOM initialization {#ready-method}
-The `ready` callback is called when an element's local DOM is ready.
+The `ready` callback is called when a {{site.project_title}} element's
+local DOM has been initialized.
+
+**What is local DOM?** Local DOM is a subtree of elements created and
+managed by your element. It's separate from the element's children,
+which are called _light DOM_ for clarity. For more information, see
+[Local DOM](local-dom.html).
+{: .alert .alert-info }
+
+An element is _ready_ when:
+
+* Its property values have been configured, with values data-bound from parents,
+ deserialized from attribute values, or else set to their default value.
-It is called after the element's template has been stamped and all elements
-**inside the element's local DOM** have been configured (with values bound from
-parents, deserialized attributes, or else default values) and had their `ready`
-method called.
+* Its local DOM template has been instantiated.
+
+* All of the elements **inside the element's local DOM** are ready, and have had
+ their `ready` methods called.
Implement `ready` when it's necessary to manipulate an element's
local DOM when the element is constructed.
@@ -235,36 +311,34 @@ local DOM when the element is constructed.
access a local DOM element.
{: .alert .alert-info }
-Within a given tree, `ready` is generally called in _document order_, but you should not
-rely on the ordering of initialization callbacks between sibling elements, or between
-a host element and its light DOM children.
+Within a given tree, `ready` is generally called in _document order_,
+but you should not rely on the ordering of initialization callbacks between
+sibling elements, or between a host element and its **light DOM** children.
### Initialization order and timing {#initialization-order}
The element's basic initialization order for a given element is:
-- `created` callback
-- local DOM initialized (This means that **local DOM** children are created,
- their property values are set as specified in the template, and `ready()`
- has been called on them)
-- `ready` callback
-- [`factoryImpl` callback](#custom-constructor) `attached` callback
+- `created` callback.
+- Local DOM initialized (This means that **local DOM** children are created,
+ their property values are set as specified in the template, and `ready`
+ has been called on them).
+- `ready` callback.
+- [`factoryImpl` callback](#custom-constructor).
+- `attached` callback.
Note that while the life cycle callbacks listed above will be called in the
described order for any given element, the **initialization timing between
-elements may vary** depending on whether or not the browser includes native
-support for web components.
+elements may vary** depending on many factors, including whether or not the
+browser includes native support for web components.
#### Initialization timing for light DOM children
-As far as initialization timing of light DOM children, there are no guarantees
-at all; in general elements are initialized in document order, so children are
-usually initialized after their parents. The user can add light children at
-any time after the parent element has been defined.
+There are no guarantees about the initialization timing of light
+DOM children. In general elements are initialized in document order,
+so children are usually initialized after their parents.
-For example, consider this light DOM for an element `avarar-list` (which would
-presumably have, in its local DOM, a `