extends ../../../ts/_cache/guide/template-syntax.jade

block includes
  include ../_util-fns
  - var _JavaScript = 'Dart';
  - var __chaining_op = '<code>;</code>';
  - var __new_op = '<code>new</code> or <code>const</code>';
  - var mapApiRef = 'https://api.dartlang.org/stable/dart-core/Map-class.html';
  - var __objectAsMap = '<b><a href="' + mapApiRef + '">Map</a></b>'

block notable-differences
  :marked
    * no support for Dart string interpolation; for example,
      instead of `"'The title is $title'"`, you must use
      `"'The title is ' + title"`
    * no support for the bitwise operators `|` and `&`
    * new [template expression operators](#expression-operators), such as `|`

block template-expressions-cannot
  :marked
    Perhaps more surprising, template expressions can’t refer to static
    properties, nor to top-level variables or functions, such as `window` or
    `document` from `dart:html`. They can’t directly call `print` or functions
    imported from `dart:math`. They are restricted to referencing members of
    the expression context.

block statement-context
  :marked
    Template statements can’t refer to static properties on the class, nor to
    top-level variables or functions, such as `window` or `document` from
    `dart:html`. They can’t directly call `print` or functions imported from
    `dart:math`.

block dart-type-exceptions
  .callout.is-helpful
    header Dart difference: Type exceptions
    :marked
      In checked mode, if the template expression result type and the target
      property type are not assignment compatible, then a type exception will
      be thrown.
      For information on checked mode, see [Important concepts](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#important-concepts)
      in the Dart language tour.

block dart-type-exception-example
  .callout.is-helpful
    header Dart difference: Type exception example
    :marked
      In checked mode, the code above will result in a type exception: 
      `String` isn't a subtype of `Hero`.

block dart-class-binding-bug
  .callout.is-helpful
    header Angular Issue #6901
    :marked
      Issue [#6901][6901] prevents us from using `[class]`. As is illustrated
      above, in the meantime we can achieve the same effect by binding to
      `className`.
      
      [6901]: http://github.com/angular/angular/issues/6901

block style-property-name-dart-diff
  .callout.is-helpful
    header Dart difference: Style property names
    :marked
      While [camelCase](glossary.html#camelcase) and
      [dash-case](glossary.html#dash-case) style property naming schemes are
      equivalent in Angular Dart, only dash-case names are recognized by the
      `dart:html` [CssStyleDeclaration][CssSD] methods `getPropertyValue()`
      and `setProperty()`. Hence, we recommend only using dash-case for style
      property names.
      
      [CssSD]: https://api.dartlang.org/stable/dart-html/CssStyleDeclaration-class.html


block dart-no-truthy-falsey
  .callout.is-helpful
    header Dart difference: No truthy/falsey values
    :marked
      In checked mode, Dart expects Boolean values
      (those with type `bool`) to be either `true` or `false`.
      Even in production mode, the only value Dart treats as `true` is
      the value `true`; all other values are `false`.
      TypeScript and JavaScript, on the other hand, treat
      many values (including non-null objects) as true.
      A TypeScript Angular program, for example, often has code like
      `*ngIf="currentHero"` where a Dart program has code like
      `*ngIf="currentHero != null"`.

      When converting TypeScript code to Dart code, watch out for
      true/false problems. For example, forgetting the `!= null`
      can lead to exceptions in checked mode, such as
      "EXCEPTION: type 'Hero' is not a subtype of type 'bool' of 'boolean expression'".
      For more information, see
      [Booleans](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#booleans)
      in the [Dart language tour](https://www.dartlang.org/docs/dart-up-and-running/ch02.html).

block remember-the-brackets
  //- Changed from RED to ORANGE, since this isn't so dire a situation in Dart.
  .callout.is-important
    header Remember the brackets!
    :marked
      Don’t make the mistake of writing `ngIf="currentHero"`!
      That syntax assigns the *string* value `"currentHero"` to `ngIf`,
      which won't work because `ngIf` expects a `bool`.

block dart-safe-nav-op
  .callout.is-helpful
    header Dart difference: ?. is a Dart operator
    :marked
      The safe navigation operator (`?.`) is part of the Dart language.
      It's considered a template expression operator because
      Angular supports `?.` even in TypeScript and JavaScript apps.

block json-pipe
  //- TODO: explain alternative in Dart
  //- {{ e | json }} --> {{ e }}
  //- which causes the object's toString() method to be invoked.
  //- Of course the `json` pipe can be used if the instance supports
  //- JSON encoding.

block null-deref-example
  :marked
    Dart throws an exception, and so does Angular:
  code-example(format="nocode").
    EXCEPTION: The null object does not have a getter 'firstName'.

block safe-op-alt
  //- N/A