diff --git a/PRIMER.md b/PRIMER.md index 1006b0fe..62e8e99a 100644 --- a/PRIMER.md +++ b/PRIMER.md @@ -22,8 +22,8 @@ Bare-minum Custom Element sugaring | [Bespoke constructor support](#bespoke-constructor) | constructor: function() { … } | [Basic lifecycle callbacks](#basic-callbacks) | created, attached, detached, attributeChanged | [Native HTML element extension](#type-extension) | extends: ‘…’ -| [Configure properties](#property-config) | propertyConfig: { … } -| [Attribute deserialization to property](#attribute-deserialization) | propertyConfig: { \: \ } +| [Configure properties](#property-config) | properties: { … } +| [Attribute deserialization to property](#attribute-deserialization) | properties: { \: \ } | [Module registry](#module-registry) | modularize, using | [Prototype Mixins](#prototype-mixins) | mixins: [ … ] @@ -46,15 +46,15 @@ Declarative data binding, events, and property nofication | [Local node marshalling](#node-marshalling) | this.$.\ | [Event listener setup](#event-listeners)| listeners: { ‘\.\’: ‘function’, ... } | [Annotated event listener setup](#annotated-listeners) | \ -| [Property change callbacks](#change-callbacks) | propertyConfig: \: { observer: ‘function’ } +| [Property change callbacks](#change-callbacks) | properties: \: { observer: ‘function’ } | [Declarative property binding](#property-binding) | \ -| [Property change notification](#property-notification) | propertyConfig: { \: { notify: true } } +| [Property change notification](#property-notification) | properties: { \: { notify: true } } | [Binding to structured data](#path-binding) | \ | [Path change notification](#set-path) | setPathValue(\, \) | [Declarative attribute binding](#attribute-binding) | \ -| [Reflecting properties to attributes](#attribute-reflection) | propertyConfig: \: { reflect: true } } +| [Reflecting properties to attributes](#attribute-reflection) | properties: \: { reflect: true } } | [Computed properties](#computed-properties) | computed: { \: ‘function(\)’ } -| [Read-only properties](#read-only) | propertyConfig: { \: { readOnly: true } } +| [Read-only properties](#read-only) | properties: { \: { readOnly: true } } | [Utility functions](#utility-functions) | toggleClass, toggleAttribute, fire, async, … | [Attribute-based layout](#layout-html) | layout.html (layout horizontal flex ...) @@ -214,9 +214,9 @@ See the [section on configuring elements](#configuring-elements) for a more in-d ## Configuring properties -Placing an object-valued `propertyConfig` property on your prototype allows you to define metadata regarding your Custom Element's properties, which can then be accessed via an API for use by other Polymer features. +Placing an object-valued `properties` property on your prototype allows you to define metadata regarding your Custom Element's properties, which can then be accessed via an API for use by other Polymer features. -By itself, the `propertyConfig` feature **doesn't do anything**. It only provides API for asking questions about these special properties (see featues below for details). +By itself, the `properties` feature **doesn't do anything**. It only provides API for asking questions about these special properties (see featues below for details). Example: @@ -225,7 +225,7 @@ Polymer({ is: 'x-custom', - propertyConfig: { + properties: { user: String, isHappy: Boolean, count: { @@ -247,7 +247,7 @@ Remember that the fields assigned to `count`, such as `readOnly` and `notify` do ## Attribute deserialization -If an attribute matches a property listed in the `propertyConfig` object, the attribute value will be assigned to a property of the same name on the element instance. Attribute values (always strings) will be automatically converted to the propertyConfig type when assigned to the property. If no other `propertyConfig` options are specified for a property, the type (specified using the type constructor, e.g. `Object`, `String`, etc.) can be set directly as the value of the property in the propertyConfig object; otherwise it should be provided as the value to the `type` key in the `propertyConfig` configuration object. +If an attribute matches a property listed in the `properties` object, the attribute value will be assigned to a property of the same name on the element instance. Attribute values (always strings) will be automatically converted to the properties type when assigned to the property. If no other `properties` options are specified for a property, the type (specified using the type constructor, e.g. `Object`, `String`, etc.) can be set directly as the value of the property in the properties object; otherwise it should be provided as the value to the `type` key in the `properties` configuration object. The type system includes support for Object values expressed as JSON, or Date objects expressed as any Date-parsable string representation. Boolean properties set based on the existence of the attribute: if the attribute exists at all, its value is true, regardless of its string-value (and the value is only false if the attribute does not exist). @@ -260,7 +260,7 @@ Example: is: 'x-custom', - propertyConfig: { + properties: { user: String, manager: { type: Boolean, @@ -666,7 +666,7 @@ Example: ## Property change callbacks (observers) -Custom element properties may be observed for changes by specifying `observer` property in the `propertyConfig` for the property that gives the name of a funciton to call. When the property changes, the change handler will be called with the new and old values as arguments. +Custom element properties may be observed for changes by specifying `observer` property in the `properties` for the property that gives the name of a funciton to call. When the property changes, the change handler will be called with the new and old values as arguments. Example: @@ -675,7 +675,7 @@ Polymer({ is: 'x-custom', - propertyConfig: { + properties: { disabled: { type: Boolean, observer: 'disabledChanged' @@ -711,7 +711,7 @@ Polymer({ is: 'x-custom', - propertyConfig: { + properties: { preload: Boolean, src: String, size: String @@ -737,7 +737,7 @@ Polymer({ is: 'x-custom', - propertyConfig: { + properties: { user: Object }, @@ -790,7 +790,7 @@ To bind to textContent, the binding annotation must currently span the entire co is: 'user-view', - propertyConfig: { + properties: { first: String, last: String } @@ -818,7 +818,7 @@ To bind to properties, the binding annotation should be provided as the value to is: 'main-view', - propertyConfig: { + properties: { user: Object } @@ -845,7 +845,7 @@ Note that currently binding to `style` is a special case which results in the va Polymer supports cooperative two-way binding between elements, allowing elements that "produce" data or changes to data to propagate those changes upwards to hosts when desired. -When a Polymer elements changes a property that was configured in `propertyConfig` with the `notify` flag set to true, it automatically fires a non-bubbling DOM event to indicate those changes to interested hosts. These events follow a naming convention of `-changed`, and contain a `value` property in the `event.detail` object indicating the new value. +When a Polymer elements changes a property that was configured in `properties` with the `notify` flag set to true, it automatically fires a non-bubbling DOM event to indicate those changes to interested hosts. These events follow a naming convention of `-changed`, and contain a `value` property in the `event.detail` object indicating the new value. As such, one could attach an `on--changed` listener to an element to be notified of changes to such properties, set the `event.detail.value` to a property on itself, and take necessary actions based on the new value. However, given this is a common pattern, bindings using "curly-braces" (e.g. `{{property}}`) will automatically perform this upwards binding automatically without the user needing to perform those tasks. This can be defeated by using "square-brace" syntax (e.g. `[[property]]`), which results in only one-way (downward) data-binding. @@ -862,7 +862,7 @@ Example 1: Two-way binding Polymer({ is: 'custom-element', - propertyConfig: { + properties: { prop: { type: String, notify: true @@ -884,7 +884,7 @@ Example 2: One-way binding (downward) + diff --git a/src/features/micro/attributes.html b/src/features/micro/attributes.html index 3d7db805..1ab24322 100644 --- a/src/features/micro/attributes.html +++ b/src/features/micro/attributes.html @@ -19,7 +19,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * * Support for mapping attributes to properties. * - * Properties that are configured in `propertyConfig` with a type are mapped + * Properties that are configured in `properties` with a type are mapped * to attributes. * * A value set in an attribute is deserialized into the specified @@ -27,7 +27,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * * Example: * - * propertyConfig: { + * properties: { * // values set to index attribute are converted to Number and propagated * // to index property * index: Number, @@ -78,7 +78,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN }, _takeAttributesToModel: function(model) { - for (var name in this.propertyConfig) { + for (var name in this.properties) { var type = this.getPropertyType(name); if (type && this.hasAttribute(name)) { this.setAttributeToProperty(model, name, type); diff --git a/src/features/micro/property-config.html b/src/features/micro/property-config.html index 505e65ef..c77f4b37 100644 --- a/src/features/micro/property-config.html +++ b/src/features/micro/property-config.html @@ -16,16 +16,16 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN /** * Define property metadata. * - * propertyConfig: { + * properties: { * : , * ... * } * * Example: * - * propertyConfig: { + * properties: { * // `foo` property can be assigned via attribute, will be deserialized to - * // the specified data-type. All `propertyConfig` properties have this behavior. + * // the specified data-type. All `properties` properties have this behavior. * foo: String, * * // `bar` property has additional behavior specifiers. @@ -39,7 +39,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * } * } * - * By itself the propertyConfig feature doesn't do anything but provide property + * By itself the properties feature doesn't do anything but provide property * information. Other features use this information to control behavior. * * The `type` information is used by the `attributes` feature to convert @@ -54,24 +54,24 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * `readOnly` properties have a getter, but no setter. To set a read-only * property, use the private setter method `_set_(value)`. * - * @class base feature: propertyConfig + * @class base feature: properties */ Base.addFeature({ - propertyConfig: { + properties: { }, nob: Object.create(null), getPropertyInfo: function(property) { - return this._getPropertyInfo(property, this.propertyConfig); + return this._getPropertyInfo(property, this.properties); }, - _getPropertyInfo: function(property, propertyConfig) { - var p = propertyConfig[property]; + _getPropertyInfo: function(property, properties) { + var p = properties[property]; if (typeof(p) === 'function') { - p = propertyConfig[property] = { + p = properties[property] = { type: p }; } diff --git a/src/features/standard/configure.html b/src/features/standard/configure.html index a236eb94..6a992338 100644 --- a/src/features/standard/configure.html +++ b/src/features/standard/configure.html @@ -68,8 +68,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN var i; // get individual default values from property config var config = {}; - for (i in this.propertyConfig) { - var c = this.propertyConfig[i]; + for (i in this.properties) { + var c = this.properties[i]; if (c.value !== undefined) { if (typeof c.value == 'function') { config[i] = c.value.call(this, this._config); diff --git a/src/features/standard/effects.html b/src/features/standard/effects.html index ad137925..8644d41e 100644 --- a/src/features/standard/effects.html +++ b/src/features/standard/effects.html @@ -16,7 +16,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN /** * Support for the declarative property sugaring via mustache `{{ }}` - * annotations in templates, and via the `propertyConfig` objects on + * annotations in templates, and via the `properties` objects on * prototypes. * * Example: @@ -25,11 +25,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * is on the hook. * * - * The `propertyConfig` object syntax is as follows: + * The `properties` object syntax is as follows: * * Polymer({ * - * propertyConfig: { + * properties: { * myProp: { * observer: 'myPropChanged', * computed: 'computemyProp(input1, input2)' @@ -44,7 +44,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * properties. * * Property effects can be created imperatively, by template-annotations - * (e.g. mustache notation), or by declaration in the `propertyConfig` object. + * (e.g. mustache notation), or by declaration in the `properties` object. * * The effect data is consumed by the `bind` subsystem (`/src/bind/*`), * which compiles the effects into efficient JavaScript that is triggered, @@ -69,7 +69,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN _prepEffects: function() { Bind.prepareModel(this); - this._addDynamicEffects(this.propertyConfig); + this._addDynamicEffects(this.properties); this._addObserverEffects(this.observers); this._addAnnotationEffects(this._annotes); Bind.createBindings(this); diff --git a/src/features/standard/notify-path.html b/src/features/standard/notify-path.html index e09d31a2..23b1dff0 100644 --- a/src/features/standard/notify-path.html +++ b/src/features/standard/notify-path.html @@ -26,7 +26,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * * is: 'x-date', * - * propertyConfig: { + * properties: { * date: { * type: Object, * notify: true diff --git a/src/lib/template/x-array-selector.html b/src/lib/template/x-array-selector.html index 5d381e3f..7f982a7a 100644 --- a/src/lib/template/x-array-selector.html +++ b/src/lib/template/x-array-selector.html @@ -15,7 +15,7 @@ using('Collection', function(Collection) { Polymer({ is: 'x-array-selector', - propertyConfig: { + properties: { items: Array, selected: { type: Object, diff --git a/src/lib/template/x-repeat.html b/src/lib/template/x-repeat.html index cae82a82..3c6ac4f5 100644 --- a/src/lib/template/x-repeat.html +++ b/src/lib/template/x-repeat.html @@ -32,7 +32,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN is: 'x-repeat', extends: 'template', - propertyConfig: { + properties: { items: { type: Array }, diff --git a/test/smoke/polymer-smoke.html b/test/smoke/polymer-smoke.html index 75568fcd..89fb794b 100644 --- a/test/smoke/polymer-smoke.html +++ b/test/smoke/polymer-smoke.html @@ -199,7 +199,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN hostAttributes: 'block', - propertyConfig: { + properties: { attribute: String }, diff --git a/test/unit/attributes-elements.html b/test/unit/attributes-elements.html index 8feff7d9..a2410aa2 100644 --- a/test/unit/attributes-elements.html +++ b/test/unit/attributes-elements.html @@ -1,7 +1,7 @@