-
-
Notifications
You must be signed in to change notification settings - Fork 109
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc(lifecycles): WIP document lifecycle #458
base: master
Are you sure you want to change the base?
Changes from 1 commit
5b32d2a
07a3d53
711405c
eea3694
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -89,18 +89,31 @@ export class CustomerDetail { | |
|
||
## The Component Lifecycle | ||
|
||
All components have a well-defined lifecycle. Below is a list of methods you can implement on your view-model in order to hook into the component lifecycle: | ||
Every component instance has a lifecycle that you can tap into. This makes it easy for you to perform various actions at particular times. For example, you may want to execute some code as soon as your component properties are bound, but before the component is first rendered. Or, you may want to run some code to manipulate the DOM as soon as possible after your element is attached to the document. Below is a summary of the various lifecycle callbacks that you can hook into in your component. | ||
|
||
| Lifecycle Callback | Description | | ||
| :--- | :--- | | ||
| `constructor` | When the framework instantiates a component, it calls your class's constructor, just like any JavaScript class. This is the best place to put basic initialization code that is not dependent on bindable properties. | | ||
| `created` | The "created" hook runs just after the constructor and can be treated very similarly. The only difference is that the component's `Controller` has been instantiated and is accessible through the `$controller` property, for advanced scenarios. | | ||
| `bind` | If your component has a method named "bind", then the framework will invoke it when it has begun binding values to your bindable properties. In terms of the component hierarchy, the bind hooks execute top-down, from parent to child, so your bindables will have their values set by the owning components, but the bindings in your view are not yet set. This is a good place to perform any work or make changes to anything that your view would depend on because data still flows down synchronously. This is the best time to do anything that might affect children as well. | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Need @bigopon to verify the timing of the |
||
| `attached` | If your component has a method named "attached", then the framework will invoke it when it has fully attached your HTML element to the document, along with its children. In terms of the component hierarchy, the attached hooks execute top-down. | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. These execute bottom up. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. My lifecycle demo
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hmm. For some reason I thought attached executed bottom up. Of course, I could be getting confused now that we have top-down and bottom-up lifecycles in v2. Thanks for verifying! There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We have been hurt by vcurrrent top-down attached. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. That's correct @3cp . There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @baerrach please add some explanation to this wrong design, plus some info on the altered design in upcoming Aurelia 2. We kept the wrong design in Aurelia vcurrent to avoid breaking change. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @3cp added known issues section with your recommendation |
||
| `detached` | If your component has a method named "detached", then the framework will invoke it when it has fully removed your HTML element from the document. In terms of the component hierarchy, the detached hooks execute bottom-up. | | ||
| `unbind` | If your component has a method named "unbind", then the framework will invoke it when it has fully disconnected bindings from your component. In terms of the component hierarchy, the unbind hooks execute bottom-up. | | ||
|
||
To tap into any of these hooks, simply implement the method on your class. | ||
|
||
<div style="border: thick solid red; border-radius: 12px; padding: 16px;"> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The signatures have changed in v2 for sure. |
||
<span style="text-align: center; font-size: 16pt;"><b>TODO</b></span> | ||
These have value, providing the method signatures, the new v2 documentation does not. I'm not sure if that is intentional or whether the signatures have changed. | ||
</div> | ||
|
||
1. `constructor()` - The view-model's constructor is called first. | ||
2. `created(owningView: View, myView: View)` - If the view-model implements the `created` callback it is invoked next. At this point in time, the view has also been created and both the view-model and the view are connected to their controller. The created callback will receive the instance of the "owningView". This is the view that the component is declared inside of. If the component itself has a view, this will be passed second. | ||
3. `bind(bindingContext: Object, overrideContext: Object)` - Databinding is then activated on the view and view-model. If the view-model has a `bind` callback, it will be invoked at this time. The "binding context" to which the component is being bound will be passed first. An "override context" will be passed second. The override context contains information used to traverse the parent hierarchy and can also be used to add any contextual properties that the component wants to add. | ||
4. `attached()` - Next, the component is attached to the DOM (in document). If the view-model has an `attached` callback, it will be invoked at this time. | ||
5. `detached()` - If defined on your view-model - is invoked after the component has been removed from the DOM. Due to navigating away or other reasons. | ||
6. `unbind()` - After a component is detached, it's usually unbound. If your view-model has the `unbind` callback, it will be invoked during this process. | ||
|
||
Each of these callbacks is optional. Implement whatever makes sense for your component, but don't feel obligated to implement any of them if they aren't needed for your scenario. Usually, if you implement `bind` you will need to implement `unbind`. The same goes for `attached` and `detached`, but again, it isn't mandatory. | ||
Every lifecycle callback is optional. Implement whatever makes sense for your component, but don't feel obligated to implement any of them if they aren't needed for your scenario. Some of the lifecycle callbacks make sense to implement in pairs (`bind/unbind`, `attached/detached`) in order to clean up any resources you have allocated. If you registered a listener or subscriber remember to remove them. | ||
|
||
The order in which the lifecycle hooks are listed above matches the order in which they are invoked. For example, `bind` happens before `attached` to ensure elements take their initial state from the view-model before the view is attached to the DOM and transitioned in. Likewise, `detached` happens before `unbind` to ensure the view is transitioned out and detached from the DOM before `unbind` potentially causes the view to change. | ||
[Aurelia Lifecycle Demo](https://codesandbox.io/embed/aurelia-lifecycle-demo-yy1tc?expanddevtools=1&autoresize=1&fontsize=18&hidenavigation=1&module=%2Fsrc%2Fapp.html&view=preview) | ||
|
||
> Info | ||
> It is important to note that if you implement the `bind` callback function, then the property changed callbacks for any `bindable` properties will not be called when the property value is initially set. The changed callback will be called for any subsequent time the bound value changes. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Need to remove the bit about the Controller since that's a new thing for au2.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've removed it, but the existing docs mention a controller, just not that its accessible via $controller.