-
-
Notifications
You must be signed in to change notification settings - Fork 111
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
Open
baerrach
wants to merge
4
commits into
aurelia:master
Choose a base branch
from
baerrach:doc/lifecycles
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
5b32d2a
doc(lifecycles): WIP document lifecycle
baerrach 07a3d53
doc(lifecycles): add component hierarchy execute order for constructo…
baerrach 711405c
doc(lifecycles): add known issue #612 router-view calls bind in wrong…
baerrach eea3694
doc(lifecycles): add known issue incorrect design choice for attached
baerrach File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -89,18 +89,48 @@ 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. In terms of the component hierarchy, the constructors execute top-down | | ||
| `created` | The "created" hook runs just after the constructor and can be treated very similarly. In terms of the component hierarchy, the created hooks execute bottom-up | | ||
| `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. | | ||
| `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. (See Known Issues: attached hooks executing top-down is an incorrect design choice)| | ||
| `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. | ||
|
||
### Known Issues ### | ||
|
||
#### Issue 612: lifecycle callbacks called in wrong sequence for top level route #### | ||
|
||
See [lifecycle callbacks called in wrong sequence for top level route.](https://github.com/aurelia/router/issues/612) | ||
|
||
Any `<router-view>` components will have their `bind` lifecycle callback be called bottom-up instead of top-down. | ||
|
||
#### attached hooks executing top-down is an incorrect design choice #### | ||
|
||
In Aurelia v2 the `attached` hooks execute bottom-up, and also includes a new `attaching` hook that execute top-down. | ||
|
||
The problem with `attached` hooks executing top-down is that the children have not yet been attached when the parent's `attached` hook is called. If you want to invoke code that requires measuring of elements or integrating a 3rd party JavaScript library that requires being mounted to the DOM you will want the children to be mounted. | ||
|
||
To work around this problem use `TaskQueue.queueTask` to schedule a task to run after children DOM elements are attached. | ||
|
||
The wrong design choice has been kept in v1 to avoid breaking changes. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 @bigopon to verify the timing of the
bind
hook. It's different between au1 and au2, so some of these details don't apply here. @bigopon has worked with the au1 code around this area most recently I believe. If I recall, thebind
hook sort of takes place in the middle of the binding process. I don't remember if the bindings in the view are set up or not actually.