From 094d967a8e72cead635efc80eba94de6d3156515 Mon Sep 17 00:00:00 2001 From: Kayce Basques Date: Wed, 11 Nov 2015 15:01:05 -0800 Subject: [PATCH 1/6] Update path observer code samples. Fixes #1384. --- 1.0/docs/devguide/properties.md | 118 +++++++++++++++++++------------- 1 file changed, 70 insertions(+), 48 deletions(-) diff --git a/1.0/docs/devguide/properties.md b/1.0/docs/devguide/properties.md index 0b5d5e3444..743356e254 100644 --- a/1.0/docs/devguide/properties.md +++ b/1.0/docs/devguide/properties.md @@ -372,36 +372,53 @@ In addition to properties, observers can also observe [paths to sub-properties]( ### Observing path changes {#observing-path-changes} -You can also observe changes to object sub-properties using the -`observers` array, by specifying a full path (`user.manager.name`) -as a function argument. +To observe changes in object paths (sub-properties): -Example: - - Polymer({ +1. Initialize your object to a default value. +2. Define an `observers` array. +3. For each object path that you want to observe, add an element to + the `observers` array. Each element must be a method call that + accepts a single argument. The argument is the value of the object path. + The method is the action that you wish to take when the object path changes. +4. Define each method in your element registration. - is: 'x-custom', - - properties: { - user: Object - }, +In order for Polymer to properly detect the path change, the path must be +updated in one of the following two ways: - observers: [ - 'userManagerChanged(user.manager)' - ], - - userManagerChanged: function(user) { - console.log('new manager name is ' + user.name); - } - - }); +* Via a [property binding](data-binding.html#property-binding). +* By calling [`set`](data-binding.html#set-path). -To observe a change to a path (object sub-property) the value **must be changed in -one of the following ways**: +Example: -* Using a Polymer [property binding](data-binding.html#property-binding) to another element. -* Using the [`set`](data-binding.html#set-path) API, which provides the - required notification to elements with registered interest. + + + + ### Deep path observation {#deep-observation} @@ -417,29 +434,34 @@ observer is a change record object with the following properties: Example: - Polymer({ - - is: 'x-custom', - - properties: { - user: Object - }, - - observers: [ - 'userManagerChanged(user.manager.*)' - ], - - userManagerChanged: function(changeRecord) { - if (changeRecord.path == 'user.manager') { - // user.manager object itself changed - console.log('new manager name is ' + changeRecord.value.name); - } else { - // sub-property of user.manager changed - console.log(changeRecord.path + ' changed to ' + changeRecord.value); - } - } - - }); + + + + ### Array observation {#array-observation} From 5bb22f1eb87054a2ba8f3ccd1ebd05aa2d90c437 Mon Sep 17 00:00:00 2001 From: Kayce Basques Date: Wed, 11 Nov 2015 15:11:52 -0800 Subject: [PATCH 2/6] s/path/sub-property --- 1.0/docs/devguide/properties.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/1.0/docs/devguide/properties.md b/1.0/docs/devguide/properties.md index 743356e254..5ce329b582 100644 --- a/1.0/docs/devguide/properties.md +++ b/1.0/docs/devguide/properties.md @@ -370,34 +370,36 @@ Example: In addition to properties, observers can also observe [paths to sub-properties](#observing-path-changes), [paths with wildcards](#deep-observation), or [array changes](#array-observation). -### Observing path changes {#observing-path-changes} +### Observing sub-property changes {#observing-path-changes} -To observe changes in object paths (sub-properties): +To observe changes in object sub-properties: 1. Initialize your object to a default value. 2. Define an `observers` array. -3. For each object path that you want to observe, add an element to +3. For each object sub-property that you want to observe, add an element to the `observers` array. Each element must be a method call that - accepts a single argument. The argument is the value of the object path. - The method is the action that you wish to take when the object path changes. + accepts a single argument. The argument is the path to the object + sub-property. The method is the action that you wish to take when the + object sub-property changes. The value of the sub-property is passed to + the method. 4. Define each method in your element registration. -In order for Polymer to properly detect the path change, the path must be -updated in one of the following two ways: +In order for Polymer to properly detect the sub-property change, the +sub-property must be updated in one of the following two ways: * Via a [property binding](data-binding.html#property-binding). * By calling [`set`](data-binding.html#set-path). Example: - + -### Deep path observation {#deep-observation} +### Deep sub-property observation {#deep-observation} To call an observer when any (deep) sub-property of an object changes, specify a path with a wildcard (`*`). From 10bda4bc1f3dc098e3b24f2e370a15ac0be815b0 Mon Sep 17 00:00:00 2001 From: Kayce Basques Date: Thu, 12 Nov 2015 11:19:11 -0800 Subject: [PATCH 3/6] Remove stuff about initializing obj to default val. --- 1.0/docs/devguide/properties.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/1.0/docs/devguide/properties.md b/1.0/docs/devguide/properties.md index 5ce329b582..490f87dc0f 100644 --- a/1.0/docs/devguide/properties.md +++ b/1.0/docs/devguide/properties.md @@ -374,15 +374,14 @@ In addition to properties, observers can also observe [paths to sub-properties]( To observe changes in object sub-properties: -1. Initialize your object to a default value. -2. Define an `observers` array. -3. For each object sub-property that you want to observe, add an element to +* Define an `observers` array. +* For each object sub-property that you want to observe, add an element to the `observers` array. Each element must be a method call that accepts a single argument. The argument is the path to the object sub-property. The method is the action that you wish to take when the object sub-property changes. The value of the sub-property is passed to the method. -4. Define each method in your element registration. +* Define each method in your element registration. In order for Polymer to properly detect the sub-property change, the sub-property must be updated in one of the following two ways: @@ -404,7 +403,6 @@ Example: user: { type: Object, value: function() { - // Observed object is initialized to default value. return {}; } } From ebc06562b9163e82af37a76e108935d3fe6920b6 Mon Sep 17 00:00:00 2001 From: Kayce Basques Date: Thu, 12 Nov 2015 11:27:19 -0800 Subject: [PATCH 4/6] use 'item' instead of 'element' in context of arrays. make content easier to read. --- 1.0/docs/devguide/properties.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/1.0/docs/devguide/properties.md b/1.0/docs/devguide/properties.md index 490f87dc0f..92225cd0dc 100644 --- a/1.0/docs/devguide/properties.md +++ b/1.0/docs/devguide/properties.md @@ -372,16 +372,15 @@ In addition to properties, observers can also observe [paths to sub-properties]( ### Observing sub-property changes {#observing-path-changes} -To observe changes in object sub-properties: +To observe changes in an object sub-property: * Define an `observers` array. -* For each object sub-property that you want to observe, add an element to - the `observers` array. Each element must be a method call that +* Add an item to the `observers` array. The item must be a method call that accepts a single argument. The argument is the path to the object sub-property. The method is the action that you wish to take when the object sub-property changes. The value of the sub-property is passed to the method. -* Define each method in your element registration. +* Define the method in your element registration. In order for Polymer to properly detect the sub-property change, the sub-property must be updated in one of the following two ways: @@ -407,7 +406,7 @@ Example: } } }, - /* Each element of observers array is a method call that takes a + /* Each item of observers array is a method call that takes a single argument. Argument is the path to the sub-property. */ observers: [ 'userNameChanged(user.name)' From 93736be1a383acdf185cc13aa8347318a22674e7 Mon Sep 17 00:00:00 2001 From: Kayce Basques Date: Thu, 12 Nov 2015 14:03:15 -0800 Subject: [PATCH 5/6] 1) Clarify that observers can be CSV list 2) s/registration/prototype --- 1.0/docs/devguide/properties.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/1.0/docs/devguide/properties.md b/1.0/docs/devguide/properties.md index 92225cd0dc..051de10064 100644 --- a/1.0/docs/devguide/properties.md +++ b/1.0/docs/devguide/properties.md @@ -372,15 +372,16 @@ In addition to properties, observers can also observe [paths to sub-properties]( ### Observing sub-property changes {#observing-path-changes} -To observe changes in an object sub-property: +To observe changes in object sub-properties: * Define an `observers` array. -* Add an item to the `observers` array. The item must be a method call that - accepts a single argument. The argument is the path to the object - sub-property. The method is the action that you wish to take when the - object sub-property changes. The value of the sub-property is passed to - the method. -* Define the method in your element registration. +* Add an item to the `observers` array. The item must be a method name + followed by a comma-separated list of one or more paths. For example, + `onNameChange(dog.name)` for one path, or + `onNameChange(dog.name, cat.name)` for multiple paths. Each path is a + sub-property that you want to observe. +* Define the method in your element prototype. When the method is called, + the argument to the method is the new value of the sub-property. In order for Polymer to properly detect the sub-property change, the sub-property must be updated in one of the following two ways: @@ -406,12 +407,14 @@ Example: } } }, - /* Each item of observers array is a method call that takes a - single argument. Argument is the path to the sub-property. */ + /* Each item of observers array is a method name followed by + a comma-separated list of one or more paths. */ observers: [ 'userNameChanged(user.name)' ], - // Each method in observers is defined in element registration. + /* Each method referenced in observers must be defined in + * element prototype. The argument to the method is the new value + * of the sub-property. */ userNameChanged: function(name) { console.log('new name: ' + name); }, From b707cf39a9930f6d6c747a570910e72d7184f89f Mon Sep 17 00:00:00 2001 From: Kayce Basques Date: Fri, 13 Nov 2015 13:30:38 -0800 Subject: [PATCH 6/6] Fix comment style in code samples. --- 1.0/docs/devguide/properties.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/1.0/docs/devguide/properties.md b/1.0/docs/devguide/properties.md index 163ec9d948..cc75024167 100644 --- a/1.0/docs/devguide/properties.md +++ b/1.0/docs/devguide/properties.md @@ -407,14 +407,14 @@ Example: } } }, - /* Each item of observers array is a method name followed by - a comma-separated list of one or more paths. */ + // Each item of observers array is a method name followed by + // a comma-separated list of one or more paths. observers: [ 'userNameChanged(user.name)' ], - /* Each method referenced in observers must be defined in - * element prototype. The argument to the method is the new value - * of the sub-property. */ + // Each method referenced in observers must be defined in + // element prototype. The argument to the method is the new value + // of the sub-property. userNameChanged: function(name) { console.log('new name: ' + name); },