port TemplateBinding to ed3266266e751b5ab1f75f8e0509d0d5f0ef35d8

pkg/template_binding/lib/src/binding_delegate.dart

+// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library template_binding.src.binding_delegate;
+
+import 'dart:html';
+import 'package:template_binding/template_binding.dart' show TemplateInstance;
+
+/**
+ * Template Bindings native features enables a wide-range of use cases,
+ * but (by design) don't attempt to implement a wide array of specialized
+ * behaviors.
+ *
+ * Enabling these features is a matter of implementing and registering a
+ * BindingDelegate. A binding delegate is an object which contains one or more
+ * delegation functions which implement specialized behavior. This object is
+ * registered via [TemplateBindExtension.bindingDelegate]:
+ *
+ * HTML:
+ *     <template bind>
+ *       {{ What!Ever('crazy')->thing^^^I+Want(data) }}
+ *     </template>
+ *
+ * Dart:
+ *     class MySyntax extends BindingDelegate {
+ *       prepareBinding(path, name, node) {
+ *         // The magic happens here!
+ *       }
+ *     }
+ *     ...
+ *     templateBind(query('template'))
+ *         ..bindingDelegate = new MySyntax()
+ *         ..model = new MyModel();
+ *
+ *
+ * See
+ * <http://www.polymer-project.org/platform/template.html#binding-delegate-api>
+ * for more information about the binding delegate.
+ */
+// TODO(jmesserly): need better api docs here. The link above seems out of date.
+abstract class BindingDelegate {
+  /**
+   * Prepares a binding. This is called immediately after parsing a mustache
+   * token with `{{ path }}` in the context of the [node] and the property named
+   * [name]. This should return a function that will be passed the actual
+   * node and model, and either returns null or an object with a `value`
+   * property. This allows the syntax to reinterpret the model for each binding.
+   */
+  PrepareBindingFunction prepareBinding(String path, String name, Node node)
+      => null;
+
+  /**
+   * Returns a function that can optionally replace the model that will be
+   * passed to [TemplateBindExtension.createInstance]. This can be used to
+   * implement syntax such as `<template repeat="{{ item in items }}">` by
+   * ensuring that the returned model has the "item" name available.
+   */
+  PrepareInstanceModelFunction prepareInstanceModel(Element template) => null;
+
+  /**
+   * Returns a function that will be called whenever the position of an item
+   * inside this template changes.
+   * this template.

[Siggi Cherem (dart-lang), 2013/10/29 21:00:07]

remove line

[Jennifer Messerly, 2013/10/29 23:07:19]

Done.

+   */
+  PrepareInstancePositionChangedFunction prepareInstancePositionChanged(
+      Element template) => null;
+}
+
+// TODO(jmesserly): removed the name parameter as it is redundant.

[Siggi Cherem (dart-lang), 2013/10/29 21:00:07]

is node redundant too, or the first node is from the inert template, while the
node below is from the live DOM tree?

[Jennifer Messerly, 2013/10/29 23:07:19]

I think it's not necessarily the same Node. needs more testing though.

+// https://github.com/Polymer/TemplateBinding/issues/146
+typedef PrepareBindingFunction(model, Node node);
+
+typedef PrepareInstanceModelFunction(model);
+
+typedef PrepareInstancePositionChangedFunction(TemplateInstance instance,
+    int index);