Angular to Aurelia Transition - Some basic questio

Question

We are thinking about using Aurelia for a new app. I come from an Angular 1 background (with some exposure to Angular 2). Aurelia seems quite nice and I really like how they have taken on the responsibility of maintaining developer workflow. However I have some questions which I cannot seem to find the answers to:

1) There are two general ways (as I understand) that one can include a web component in a page. These are <compose> and write a custom element. My question is, coming from Angular there is a big emphasis on scopes (i.e. what is in scope at a specific point in the DOM). I am wondering what is in "scope" (i.e. available to binding expression) withing compose and custom elements. I mean, is a parent view-model available within a child template? If so, do child view-model properties hide/shadow the parent view-model properties?

2) In Angular 2, there are guidelines with respect to how data is passed in and out of components. We are not supposed to change non-primitives that are bound to a component (because that forces Angular 2's change detection to always go into that component branch to check all properties).

Are there any guidelines/info to passing data in and out of components in Aurelia? I mean from the reading that I have done it sounds like I would just use value.bind to bind to all the @bindable properties. Is that correct? Are these two-way bound by default or do I have to explicitly declare value.two-way? Is there anything wrong with changing the properties of a two-way bound object?

Thanks in advance

Answer 1

Great questions- here's some info:

1) There are two general ways (as I understand) that one can include a web component in a page. These are <compose> and write a custom element. My question is, coming from Angular there is a big emphasis on scopes (i.e. what is in scope at a specific point in the DOM). I am wondering what is in "scope" (i.e. available to binding expression) within compose and custom elements. I mean, is a parent view-model available within a child template? If so, do child view-model properties hide/shadow the parent view-model properties?

Consider the following markup:

app.html

<template>
  <h1>${message}</h1>

  <date-picker value.bind="startDate"></date-picker>

  <compose view="footer.html"></compose>
<template>

<compose> preserves access to the outer scope. When the template contained in footer.html is data-bound, it will have access to whatever app.html is bound to- for example, it could access the message property.

A custom element's template cannot access the outer scope. Custom elements are intended to be encapsulated and portable. For this reason they are not allowed to access the outer scope, preventing developers from creating custom elements that expect to be used in specific binding contexts. The primary way to get data in/out of a custom element is through @bindable properties (similar to dependency-properties in XAML).

2) In Angular 2, there are guidelines with respect to how data is passed in and out of components. We are not supposed to change non-primitives that are bound to a component (because that forces Angular 2's change detection to always go into that component branch to check all properties).

Are there any guidelines/info to passing data in and out of components in Aurelia? I mean from the reading that I have done it sounds like I would just use value.bind to bind to all the @bindable properties. Is that correct?

correct

Are these two-way bound by default or do I have to explicitly declare value.two-way? Is there anything wrong with changing the properties of a two-way bound object?

Aurelia automatically chooses the correct default binding mode for attributes of built-in elements like inputs or selects. You need to specify the defaults for custom elements if you want something other than one-way. Here's how to do that:

import {bindingMode} from 'aurelia-framework'; // or 'aurelia-binding';

export class DatePicker {
  @bindable({ defaultBindingMode: bindingMode.twoWay }) value;  // <----
  @bindable min = new Date(1900, 0, 1);
  @bindable max = new Date(2250, 11, 31);
  ...
}

Answer 2

You can use <compose> as a wildcard declaration. So instead of declaring the web component, like <my-component></my-component> you can do

<compose view-model.bind="variableContainingModel" model.bind="variableContainingViewModelPath"></compose>

or just

<compose view-model="./my-component.html" model="./my-component.js"></compose>

Update from Jeremy Danyow's answer

The compose tag preserves access to the outer scope. When the template is data-bound, it will have access to its parent's properties.

A custom component sees all properties declared in its view-model. If you want to share any parent view-model object to the component, you can use bindable properties.

import {bindable} from 'aurelia-framework';
export class MyComponent {
   @bindable propertyFromMyParent;
}

view:

<template>
   <div>${propertyFromMyParent}</div>
</template>

//parent call
<my-component propertyFromMyParent.bind="someProperty"></my-component>

Bindable properties are one-way by default. You can override this using:

import {bindable, bindingMode} from 'aurelia-framework';
@bindable({ defaultBindingMode: bindingMode.twoWay }) propertyFromMyParent

There is also the content tag which very useful:

<template>
   <content></content>
</template>

//parent call
<my-component>Some Content Here</my-component>

Hope this helps!