| Index: packages/polymer_expressions/README.md
|
| diff --git a/packages/polymer_expressions/README.md b/packages/polymer_expressions/README.md
|
| deleted file mode 100644
|
| index 6f0db0153130df0980635089a73211ea36f2c33b..0000000000000000000000000000000000000000
|
| --- a/packages/polymer_expressions/README.md
|
| +++ /dev/null
|
| @@ -1,297 +0,0 @@
|
| -polymer_expressions
|
| -===================
|
| -
|
| -
|
| -Polymer expressions are an expressive syntax that can be used in HTML templates
|
| -with Dart.
|
| -
|
| -Templates are one feature of Polymer.dart, which is a set of comprehensive UI
|
| -and utility components for building web applications.
|
| -This package is automatically included with the
|
| -[Polymer](https://pub.dartlang.org/packages/polymer) package
|
| -because Polymer expressions are the default expression syntax
|
| -in Polymer Dart apps.
|
| -The [Polymer.dart homepage][home_page]
|
| -contains a list of features, project status,
|
| -installation instructions, tips for upgrading from Web UI,
|
| -and links to other documentation.
|
| -
|
| -
|
| -## Overview
|
| -
|
| -Polymer expressions allow you to write complex binding expressions, with
|
| -property access, function invocation, list/map indexing, and two-way filtering
|
| -like:
|
| -
|
| -```html
|
| - {{ person.title + " " + person.getFullName() | upppercase }}
|
| -```
|
| -
|
| -### Model-Driven Views (MDV)
|
| -[MDV][mdv] allows you to define templates directly in HTML that are rendered by
|
| -the browser into the DOM. Templates are bound to a data model, and changes to
|
| -the data are automatically reflected in the DOM, and changes in HTML inputs are
|
| -assigned back into the model. The template and model are bound together via
|
| -binding expressions that are evaluated against the model. These binding
|
| -expressions are placed in double-curly-braces, or "mustaches".
|
| -
|
| -Example:
|
| -
|
| -```html
|
| - <template>
|
| - <p>Hello {{ person.name }}</p>
|
| - </template>
|
| -```
|
| -
|
| -MDV includes a very basic binding syntax which only allows a series of
|
| -dot-separate property names.
|
| -
|
| -[mdv]: http://www.polymer-project.org/platform/mdv.html
|
| -
|
| -### Custom binding syntaxes with binding delegate
|
| -
|
| -While MDV's built-in syntax is very basic, it does allow custom syntaxes called
|
| -"binding delegates" to be installed and used. A binding delegate can interpret
|
| -the contents of mustaches however it likes. PolymerExpressions is such a
|
| -binding delegate.
|
| -
|
| -Example:
|
| -
|
| -```html
|
| - <template bind>
|
| - <p>Hello {{ person.title + " " + person.getFullName() | uppercase }}</p>
|
| - </template>
|
| -```
|
| -
|
| -## Usage
|
| -
|
| -### Installing from Pub
|
| -
|
| -Add the following to your pubspec.yaml file:
|
| -
|
| -```yaml
|
| - dependencies:
|
| - polymer_expressions: any
|
| -```
|
| -
|
| -Hint: check https://pub.dartlang.org/packages/polymer_expressions for the latest
|
| -version number.
|
| -
|
| -Then import polymer_expressions.dart:
|
| -
|
| - import 'package:polymer_expressions/polymer_expressions.dart';
|
| -
|
| -### Registering a binding delegate
|
| -
|
| -**Polymer Expressions are now the default syntax for `<polymer-element>` custom
|
| -elements.**
|
| -
|
| -You do not need to manually register the bindingDelegate if your bindings are
|
| -inside a custom element. However, if you want to use polymer_expressions outside
|
| -a custom element, read on:
|
| -
|
| -Binding delegates must be installed on a template before they can be used.
|
| -For example, set the bindingDelegate property of your template
|
| -elements to an instance of PolymerExpressions. The templates will then use the
|
| -PolymerExpressions instance to interpret
|
| -binding expressions.
|
| -
|
| -```dart
|
| - import 'dart:html';
|
| - import 'package:polymer_expressions/polymer_expressions.dart';
|
| -
|
| - main() {
|
| - var template = query('#my_template');
|
| - template.bindingDelegate = new PolymerExpressions();
|
| - }
|
| -```
|
| -
|
| -### Registering top-level variables
|
| -
|
| -Before a top-level variable can be used, it must be registered. The
|
| -PolymerExpressions constructor takes a map of named values to use as variables.
|
| -
|
| -```dart
|
| - main() {
|
| - var globals = {
|
| - 'uppercase': (String v) => v.toUpperCase(),
|
| - 'app_id': 'my_app_123',
|
| - };
|
| - var template = query('#my_template');
|
| - template.bindingDelegate = new PolymerExpressions(globals: globals);
|
| - }
|
| -```
|
| -
|
| -## Features
|
| -
|
| -### The model and scope
|
| -
|
| -Polymer Expressions allow binding to more than just the model assigned to a
|
| -template instance. Top-level variables can be defined so that you can use
|
| -filters, global variables and constants, functions, etc. These variables and the
|
| -model are held together in a container called a Scope. Scopes can be nested,
|
| -which happens when template tags are nested.
|
| -
|
| -### Two-way bindings
|
| -
|
| -Bindings can be used to modify the data model based on events in the DOM. The
|
| -most common case is to bind an <input> element's value field to a model
|
| -property and have the property update when the input changes. For this to work,
|
| -the binding expression must be "assignable". Only a subset of expressions are
|
| -assignable. Assignable expressions cannot contain function calls, operators, and
|
| -any index operator must have a literal argument. Assignable expressions can
|
| -contain filter operators as long as all the filters are two-way transformers.
|
| -
|
| -Some restrictions may be relaxed further as allowed.
|
| -
|
| -Assignable Expressions:
|
| -
|
| - * `foo`
|
| - * `foo.bar`
|
| - * `items[0].description`
|
| - * `people['john'].name`
|
| - * `product.cost | convertCurrency('ZWD')` where `convertCurrency` evaluates to
|
| - a Tranformer object.
|
| -
|
| -Non-Assignable Expressions:
|
| -
|
| - * `a + 1`
|
| - * `!c`
|
| - * `foo()`
|
| - * `person.lastName | uppercase` where `uppercase` is a filter function.
|
| -
|
| -### Null-Safety
|
| -
|
| -Expressions are generally null-safe. If an intermediate expression yields `null`
|
| -the entire expression will return null, rather than throwing an exception.
|
| -Property access, method invocation and operators are null-safe. Passing null to
|
| -a function that doesn't handle null will not be null safe.
|
| -
|
| -### Streams
|
| -
|
| -Polymer Expressions have experimental support for binding to streams, and when
|
| -new values are passed to the stream, the template updates. The feature is not
|
| -fully implemented yet.
|
| -
|
| -See the examples in /example/streams for more details.
|
| -
|
| -## Syntax
|
| -
|
| -### Property access
|
| -
|
| -Properties on the model and in the scope are looked up via simple property
|
| -names, like `foo`. Property names are looked up first in the top-level
|
| -variables, next in the model, then recursively in parent scopes. Properties on
|
| -objects can be access with dot notation like `foo.bar`.
|
| -
|
| -The keyword `this` always refers to the model if there is one, otherwise `this`
|
| -is `null`. If you have model properties and top-level variables with the same
|
| -name, you can use `this` to refer to the model property.
|
| -
|
| -### Literals
|
| -
|
| -Polymer Expressions support number, boolean, string, and map literals. Strings
|
| -can use either single or double quotes.
|
| -
|
| - * Numbers: `1`, `1.0`
|
| - * Booleans: `true`, `false`
|
| - * Strings: `'abc'`, `"xyz"`
|
| - * Maps: `{ 'a': 1, 'b': 2 }`
|
| -
|
| -List literals are planned, see [issue 9](https://github.com/dart-lang/polymer_expressions/issues/9)
|
| -
|
| -### Functions and methods
|
| -
|
| -If a property is a function in the scope, a method on the model, or a method on
|
| -an object, it can be invoked with standard function syntax. Functions and
|
| -Methods can take arguments. Named arguments are not supported. Arguments can be
|
| -literals or variables.
|
| -
|
| -Examples:
|
| -
|
| - * Top-level function: `myFunction()`
|
| - * Top-level function with arguments: `myFunction(a, b, 42)`
|
| - * Model method: `aMethod()`
|
| - * Method on nested-property: `a.b.anotherMethod()`
|
| -
|
| -### Operators
|
| -
|
| -Polymer Expressions supports the following binary and unary operators:
|
| -
|
| - * Arithmetic operators: +, -, *, /, %, unary + and -
|
| - * Comparison operators: ==, !=, <=, <, >, >=
|
| - * Boolean operators: &&, ||, unary !
|
| -
|
| -Expressions do not support bitwise operators such as &, |, << and >>, or increment/decrement operators (++ and --)
|
| -
|
| -### List and Map indexing
|
| -
|
| -List and Map like objects can be accessed via the index operator: []
|
| -
|
| -Examples:
|
| -
|
| - * `items[2]`
|
| - * `people['john']`
|
| -
|
| -Unlike JavaScript, list and map contents are not generally available via
|
| -property access. That is, the previous examples are not equivalent to `items.2`
|
| -and `people.john`. This ensures that access to properties and methods on Lists
|
| -and Maps is preserved.
|
| -
|
| -### Filters and transformers
|
| -
|
| -A filter is a function that transforms a value into another, used via the pipe
|
| -syntax: `value | filter` Any function that takes exactly one argument can be
|
| -used as a filter.
|
| -
|
| -Example:
|
| -
|
| -If `person.name` is "John", and a top-level function named `uppercase` has been
|
| -registered, then `person.name | uppercase` will have the value "JOHN".
|
| -
|
| -The pipe syntax is used rather than a regular function call so that we can
|
| -support two-way bindings through transformers. A transformer is a filter that
|
| -has an inverse function. Transformers must extend or implement the `Transformer`
|
| -class, which has `forward()` and `reverse()` methods.
|
| -
|
| -### Repeating templates
|
| -
|
| -A template can be repeated by using the "repeat" attribute with a binding. The
|
| -binding can either evaluate to an Iterable, in which case the template is
|
| -instantiated for each item in the iterable and the model of the instance is
|
| -set to the item, or the binding can be a "in" iterator expression, in which
|
| -case a new variable is added to each scope.
|
| -
|
| -The following examples produce the same output.
|
| -
|
| -Evaluate to an iterable:
|
| -
|
| -```html
|
| - <template repeat="{{ items }}">
|
| - <div>{{ }}</div>
|
| - </template>
|
| -```
|
| -
|
| -"in" expression:
|
| -
|
| -```html
|
| - <template repeat="{{ item in items }}">
|
| - <div>{{ item }}</div>
|
| - </template>
|
| -```
|
| -
|
| -## Status
|
| -
|
| -The syntax implemented is experimental and subject to change, in fact, it
|
| -**will** change soon. The goal is to be compatible with Polymer's binding
|
| -syntax. We will announce breaking changes on the
|
| -[web-ui@dartlang.org mailing list][web-ui-list].
|
| -
|
| -Please [file issues on Dart project page](http://dartbug.com/new)
|
| -for any bugs you find or for feature requests. Make a note that it applies to
|
| -"package:polymer_expressions"
|
| -
|
| -You can discuss Polymer Expressions on the
|
| -[web-ui@dartlang.org mailing list][web-ui-list].
|
| -
|
| -[web-ui-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/web-ui
|
|
|