Skip to content

Commit 0ede79a

Browse files
author
Steven Orvell
committed
Add docs
1 parent 54911a7 commit 0ede79a

7 files changed

Lines changed: 87 additions & 22 deletions

‎src/lib/dom-api-classlist.html‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,12 @@
1414

1515
var DomApi = Polymer.DomApi.ctor;
1616

17+
/**
18+
* DomApi.classList allows maniuplation of `classList` compatible with
19+
* Polymer.dom. The general usage is
20+
* `Polymer.dom(node).classList.method(arguments)` where methods and arguments
21+
* match native DOM.
22+
*/
1723
Object.defineProperty(DomApi.prototype, 'classList', {
1824
get: function() {
1925
if (!this._classList) {

‎src/lib/dom-api-event.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,16 @@
1515
var DomApi = Polymer.DomApi.ctor;
1616
var Settings = Polymer.Settings;
1717

18+
19+
/**
20+
* DomApi.Event allows maniuplation of events compatible with
21+
* the scoping concepts in Shadow DOM and compatible with both Shady DOM
22+
* and Shadow DOM. The general usage is
23+
* `Polymer.dom(event).property`. The `path` property returns `event.path`
24+
* matching Shadow DOM. The `rootTarget` property returns the first node
25+
* in the `path` and is the original event target. The `localTarget` property
26+
* matches event.target under Shadow DOM and is the scoped event target.
27+
*/
1828
DomApi.Event = function(event) {
1929
this.event = event;
2030
};

‎src/lib/dom-api-flush.html‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,14 @@
99
-->
1010
<script>
1111

12-
// add Polymer.dom flush api...
12+
/**
13+
* `Polymer.dom.flush()` causes any asynchronously queued actions to be
14+
* flushed synchronously. It should be used sparingly as calling it frequently
15+
* can negatively impact performance since work is often deferred for
16+
* efficiency. Calling `Polymer.dom.flush()` is useful, for example, when
17+
* an element has to measure itself and is unsure about the state of its
18+
* internal or compoased DOM.
19+
*/
1320
Polymer.Base.extend(Polymer.dom, {
1421

1522
_flushGuard: 0,

src/lib/dom-api-mutation-content.html renamed to src/lib/dom-api-observe-distributed-nodes.html

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,21 @@
1515
var DomApi = Polymer.DomApi.ctor;
1616
var Settings = Polymer.Settings;
1717

18-
DomApi.MutationContent = function(domApi) {
19-
DomApi.Mutation.call(this, domApi);
18+
/**
19+
* DomApi.ObserveDistributedNodes notifies when the list returned by
20+
* a <content> element's `getDistributedNodes()` may have changed.
21+
* It is not meant to be used directly; it is used by
22+
* `Polymer.dom(node).observeNodes(callback)` to observe changes to
23+
* `<content>.getDistributedNodes()`.
24+
*/
25+
DomApi.ObserveDistributedNodes = function(domApi) {
26+
DomApi.ObserveNodes.call(this, domApi);
2027
};
2128

22-
DomApi.MutationContent.prototype = Object.create(DomApi.Mutation.prototype);
29+
DomApi.ObserveDistributedNodes.prototype =
30+
Object.create(DomApi.ObserveNodes.prototype);
2331

24-
Polymer.Base.extend(DomApi.MutationContent.prototype, {
32+
Polymer.Base.extend(DomApi.ObserveDistributedNodes.prototype, {
2533

2634
// NOTE: ShadyDOM distribute provokes notification of these observers
2735
// so no setup is required.
@@ -41,7 +49,7 @@
4149

4250
if (Settings.useShadow) {
4351

44-
Polymer.Base.extend(DomApi.MutationContent.prototype, {
52+
Polymer.Base.extend(DomApi.ObserveDistributedNodes.prototype, {
4553

4654
// NOTE: Under ShadowDOM we must observe the host element for
4755
// changes.

src/lib/dom-api-mutation.html renamed to src/lib/dom-api-observe-nodes.html

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,19 @@
1616
var Settings = Polymer.Settings;
1717
var hasDomApi = Polymer.DomApi.hasDomApi;
1818

19-
DomApi.Mutation = function(domApi) {
19+
/**
20+
* DomApi.ObserveNodes tracks changes to an element's effective child nodes,
21+
* the same list returned from `Polymer.dom(node).getEffectiveChildNodes()`.
22+
* It is not meant to be used directly; it is used by
23+
* `Polymer.dom(node).observeNodes(callback)` to observe changes.
24+
*/
25+
DomApi.ObserveNodes = function(domApi) {
2026
this.domApi = domApi;
2127
this.node = this.domApi.node;
2228
this._listeners = [];
2329
};
2430

25-
DomApi.Mutation.prototype = {
31+
DomApi.ObserveNodes.prototype = {
2632

2733
addListener: function(callback) {
2834
if (!this._isSetup) {
@@ -167,12 +173,13 @@
167173

168174
if (Settings.useShadow) {
169175

170-
var baseSetup = DomApi.Mutation.prototype._setup;
171-
var baseCleanup = DomApi.Mutation.prototype._cleanup;
176+
var baseSetup = DomApi.ObserveNodes.prototype._setup;
177+
var baseCleanup = DomApi.ObserveNodes.prototype._cleanup;
172178

173-
var beforeCallListeners = DomApi.Mutation.prototype._beforeCallListeners;
179+
var beforeCallListeners = DomApi.ObserveNodes
180+
.prototype._beforeCallListeners;
174181

175-
Polymer.Base.extend(DomApi.Mutation.prototype, {
182+
Polymer.Base.extend(DomApi.ObserveNodes.prototype, {
176183

177184
_setup: function() {
178185
if (!this._observer) {

‎src/lib/dom-api.html‎

Lines changed: 35 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@
1111
<link rel="import" href="dom-innerHTML.html">
1212
<script>
1313

14+
/**
15+
* DomApi is a dom manipulation library which is compatible with both
16+
* Shady DOM and Shadow DOM. The general usage is
17+
* `Polymer.dom(node).method(arguments)` where methods and arguments
18+
* match native DOM where possible.
19+
*/
1420
Polymer.DomApi = (function() {
1521
'use strict';
1622

@@ -462,6 +468,11 @@
462468
return list;
463469
},
464470

471+
/*
472+
Returns a list of effective childNoes within this element. These can be
473+
dom child nodes or elements distributed to children that are insertion
474+
points.
475+
*/
465476
getEffectiveChildNodes: function() {
466477
var list = [];
467478
var c$ = this.childNodes;
@@ -526,15 +537,34 @@
526537
return n;
527538
},
528539

540+
/**
541+
* Notifies callers about changes to the element's effective child nodes,
542+
* the same list as returned by `getEffectiveChildNodes`.
543+
* @param {function} callback The supplied callback is called with an
544+
* `info` argument which is an object that provides
545+
* the `target` on which the changes occurred, a list of any nodes
546+
* added in the `addedNodes` array, and nodes removed in the
547+
* `removedNodes` array.
548+
* @return {object} Returns a handle which is the argument to
549+
* `unobserveNodes`.
550+
*/
529551
observeNodes: function(callback) {
530-
if (!this.observer) {
531-
this.observer = this.node.localName === CONTENT ?
532-
new DomApi.MutationContent(this) :
533-
new DomApi.Mutation(this);
552+
if (callback) {
553+
if (!this.observer) {
554+
this.observer = this.node.localName === CONTENT ?
555+
new DomApi.ObserveDistributedNodes(this) :
556+
new DomApi.ObserveNodes(this);
557+
}
558+
return this.observer.addListener(callback);
534559
}
535-
return this.observer.addListener(callback);
536560
},
537561

562+
/**
563+
* Stops observing changes to the element's effective child nodes.
564+
* @param {object} handle The handle for the callback that should
565+
* no longer receive notifications. This handle is returned from
566+
* `observeNodes`.
567+
*/
538568
unobserveNodes: function(handle) {
539569
if (this.observer) {
540570
this.observer.removeListener(handle);

‎src/mini/shady.html‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,18 +12,15 @@
1212
<link rel="import" href="../lib/dom-api-flush.html">
1313
<link rel="import" href="../lib/dom-api-event.html">
1414
<link rel="import" href="../lib/dom-api-classlist.html">
15-
<link rel="import" href="../lib/dom-api-mutation.html">
16-
<link rel="import" href="../lib/dom-api-mutation-content.html">
15+
<link rel="import" href="../lib/dom-api-observe-nodes.html">
16+
<link rel="import" href="../lib/dom-api-observe-distributed-nodes.html">
1717
<script>
1818

1919
(function() {
2020
/**
21-
2221
Implements a pared down version of ShadowDOM's scoping, which is easy to
2322
polyfill across browsers.
24-
2523
*/
26-
2724
var hasDomApi = Polymer.DomApi.hasDomApi;
2825

2926
Polymer.Base._addFeature({

0 commit comments

Comments
 (0)