Exploring Directives, $scope, DOM Rendering, And Timing In AngularJS
AngularJS provides a powerful glue that binds your View Model ($scope) to your View (HTML) using an inline, declarative syntax. As directives get linked and your $scope values change, AngularJS works quickly to update the DOM (Document Object Model) as needed. At the same time, AngularJS also needs to alert Controllers to changes in the $scope. The timing of all of this can be more than a bit tricky to understand. As such, I wanted to take a quick look at how the DOM tree structure influences which data points are available at what time.
NOTE: I didn't really get to cover everything in the video that I would have liked. I think I also said "breadth-first" a few times. I meant depth-first.
For this demo, I want to look primarily at how directives get linked; and, what those directives know about the view model and the DOM. In the following HTML document, we have a DOM tree that has three branches: Branch A, Branch B, and Branch C. Each node in each branch has a directive - bnLifecycle - which logs the linking of the directive and then watches for changes in the inherited $scope. We also have an ngRepeat directive at the bottom of Branch C which renders Span tags based on the view model.
To make this demo interesting - and to really get at the nutmeat of what's going on - we're not going to render the entire Document Object Model at load time. Rather, we're going to use ngSwitch directives to dynamically add Branch B and the ngRepeat to the DOM tree on demand.
| <!doctype html> | |
| <html ng-app="Demo" ng-controller="DemoController"> | |
| <head> | |
| <meta charset="utf-8" /> | |
| <title> | |
| Exploring Directives, DOM Rendering, And Timing In AngularJS | |
| </title> | |
| <style type="text/css"> | |
| div { | |
| border: 1px solid #CCCCCC ; | |
| padding: 10px 10px 10px 10px ; | |
| } | |
| div + div, | |
| div + section, | |
| section + div { | |
| margin-top: 10px ; | |
| } | |
| </style> | |
| </head> | |
| <body> | |
| <h1> | |
| Exploring Directives, DOM Rendering, And Timing In AngularJS | |
| </h1> | |
| <p> | |
| <a ng-click="addRepeater()">Add Repeater</a> - | |
| <a ng-click="addBranchB()">Add Branch B</a> - | |
| <a ng-click="addValue()">Add Value</a> | |
| </p> | |
| <!-- BEGIN: Nested Directives. --> | |
| <div id="Root" bn-lifecycle> | |
| <!-- Static branch. --> | |
| <div id="Branch-A-1" bn-lifecycle> | |
| <div id="Branch-A-2" bn-lifecycle> | |
| <span> | |
| Branch A | |
| </span> | |
| </div> | |
| </div> | |
| <!-- Dynamically included branch. --> | |
| <section ng-switch="showBranchB"> | |
| <div ng-switch-when="true" id="Branch-B-1" bn-lifecycle> | |
| <div id="Branch-B-2" bn-lifecycle> | |
| <span> | |
| Branch B | |
| </span> | |
| </div> | |
| </div> | |
| </section> | |
| <!-- Static branch with dynamically included ngRepeat. --> | |
| <div id="Branch-C-1" bn-lifecycle> | |
| <div ng-switch="includeRepeater" id="Branch-C-2" bn-lifecycle> | |
| <span> | |
| Branch C : | |
| </span> | |
| <!-- Dynamically included ngRepeat. --> | |
| <span ng-switch-when="true" id="Branch-C-3" bn-lifecycle> | |
| <span ng-repeat="value in values" class="value"> | |
| Value | |
| </span> | |
| </span> | |
| </div> | |
| </div> | |
| </div> | |
| <!-- END: Nested Directives. --> | |
| <!-- Load jQuery and AngularJS from the CDN. --> | |
| <script | |
| type="text/javascript" | |
| src="//code.jquery.com/jquery-1.9.0.min.js"> | |
| </script> | |
| <script | |
| type="text/javascript" | |
| src="//ajax.googleapis.com/ajax/libs/angularjs/1.0.2/angular.min.js"> | |
| </script> | |
| <script type="text/javascript"> | |
| // Create an application module for our demo. | |
| var Demo = angular.module( "Demo", [] ); | |
| // -------------------------------------------------- // | |
| // -------------------------------------------------- // | |
| // Define the root-level controller for the application. | |
| Demo.controller( | |
| "DemoController", | |
| function( $scope ) { | |
| // I add the dynamic branch into the DOM tree. | |
| $scope.addBranchB = function() { | |
| $scope.showBranchB = true; | |
| }; | |
| // I add the ngRepeat to the DOM so that the collection | |
| // can be rendered. | |
| $scope.addRepeater = function() { | |
| $scope.includeRepeater = true; | |
| }; | |
| // I add a value to the collection. | |
| $scope.addValue = function() { | |
| $scope.values.push( "value" ); | |
| }; | |
| // --- | |
| // I hold the collection that will be ngRepeat'd in | |
| // the DOM. | |
| $scope.values = [ "value" ]; | |
| // I flag whether or not Branch B is in the DOM. | |
| $scope.showBranchB = false; | |
| // I flag whether or not the ngRepeat is in the DOM. | |
| $scope.includeRepeater = false; | |
| // -- | |
| // Listen for changes in the value collection. | |
| $scope.$watch( | |
| "values.length", | |
| function( newValue, oldValue ) { | |
| // Ignore first run that results from initial | |
| // watching binding. | |
| if ( newValue === oldValue ) { | |
| return; | |
| } | |
| console.log( "Demo Controller" ); | |
| console.log( "...", newValue, "in memory" ); | |
| } | |
| ); | |
| } | |
| ); | |
| // -------------------------------------------------- // | |
| // -------------------------------------------------- // | |
| // I track the both the linking of the DOM elements and the | |
| // mutation of the values collection. | |
| Demo.directive( | |
| "bnLifecycle", | |
| function() { | |
| // I link the DOM element to the view model. | |
| function link( $scope, element, attributes ) { | |
| // Log that the directive has been linked. | |
| console.log( "Linked:", attributes.id ); | |
| // Listen for changes in the values collection. | |
| // When it changes, log the in-memory length in | |
| // comparison to the in-DOM length of the elements | |
| // generated based on the collection. | |
| $scope.$watch( | |
| "values.length", | |
| function( newValue, oldValue ) { | |
| // Ignore first run that results from | |
| // initial watching binding. | |
| if ( newValue === oldValue ) { | |
| return; | |
| } | |
| // Gather the ngRepeat'd DOM elements. | |
| var values = $( "span.value" ); | |
| console.log( attributes.id ); | |
| console.log( | |
| "...", | |
| newValue, // In-memory. | |
| "in memory,", | |
| values.length, // In-DOM rendering. | |
| "in DOM" | |
| ); | |
| } | |
| ); | |
| } | |
| // Return directive configuration. | |
| return({ | |
| link: link, | |
| restrict: "A" | |
| }); | |
| } | |
| ); | |
| </script> | |
| </body> | |
| </html> |
When we first load the page, the only visible activity we have is the linking of the [static] directives. In our case, that's Branch A and half of Branch C. Our bnLifecycle directive logs its own linking on these rendered DOM nodes which leaves us with the initial console output:
Linked: Branch-A-2
Linked: Branch-A-1
Linked: Branch-C-2
Linked: Branch-C-1
Linked: Root
As you can see, directives are linked in a Depth-First, Bottom-Up approach to the DOM (Document Object Model) tree. This has some important implications about what the directives can do at link time. Since they are applied in a bottom-up approach, we know that, at link time, the descendant nodes of the directive's element have all been fully rendered. We also know that the previous-sibling nodes of the directive's element have been fully rendered as well. What we don't know about the DOM, however, is anything about the parent node or the next-sibling nodes of the directive's element.
NOTE: The ngController directive is a special kind of directive that has its own link timing. Controllers are linked in a top-down manner, which will become evident when we look at the $watch()-based output.
Now that we have our initial DOM rendering, I'm going to click on the following links in order:
- Add Repeater
- Add Branch B
This will dynamically add the rest of Branch C (the repeater) and the entirety of Branch B to the current DOM tree. As these elements are added to the document, AngularJS links the bnLifecycle and ngRepeat directives, giving us some more output in our console:
Linked: Branch-C-3
Linked: Branch-B-2
Linked: Branch-B-1
Again, we see that AngularJS links directives in a depth-first, bottom-up approach.
Before we perform the next action, let's be very cognizant about the order of operations in which the DOM has been constructed:
The ngRepeat was added to the DOM before Branch B was added to the DOM. In other words, Branch B was added to the DOM after AngularJS has already linked the ngRepeat directive.
Let that sink in for a second as it's critical to understanding the timing of all of this.
Ok, now let's use the "Add Value" link to add a value to our rendered collection. And remember, each directive (and the root Controller) is watching the $scope for changes in the length of the collection. And, when this change occurs, the new value is logged along with the directive's view into the currently-rendered Document Object Model.
When I click on the "Add Value" link, a new item is added to the "values" collection which triggers all of the relevant $watch() bindings. This results in the following console output:
Demo Controller
... 2 in memory
Branch-A-2
... 2 in memory, 1 in DOM
Branch-A-1
... 2 in memory, 1 in DOM
Branch-C-2
... 2 in memory, 1 in DOM
Branch-C-1
... 2 in memory, 1 in DOM
Root
... 2 in memory, 1 in DOM
Branch-C-3
... 2 in memory, 2 in DOM
Branch-B-2
... 2 in memory, 2 in DOM
Branch-B-1
... 2 in memory, 2 in DOM
At first, this output might not make any sense at all. On the one hand, things sort of look like they are firing in a depth-first, bottom-up approach; but, on the other hand, this clearly doesn't hold true for all of the log values. The fact is, $watch() bindings have almost nothing to do with the struct of the DOM at all. $watch() bindings are triggered in the same order in which they were bound; the DOM merely influences the order in which directives are linked, which in turn, influences the order in which the $watch() bindings are created.
Oh, and don't forget, ngRepeat is just a directive - like bnLifecycle. And, just like bnLifecycle, it uses $watch() bindings to know when the values collection has changed. This means that the ability of ngRepeat to update the DOM is subservient to the relative timing of its own $watch() bindings. This is why Branch B knows about the DOM changes precipitated by Branch C-3 - the $watch() bindings in Branch B were created after Branch C-3 was added to the DOM.
The timing of all of this stuff can be a bit complicated. Hopefully this exploration has helped clear things up a bit. Since nested directives can't always depend on a predictable structure, you can use "directive controllers" to facilitate inter-directive communication; but that's something I'm still trying to wrap my head around.
Want to use code from this post? Check out the license.
Reader Comments
Style question Ben: what's with all the empty lines? I distrust code the more I have to scroll to understand it. One Line should equal = One Logical Statement wherever possible.
Hey Marc,
See:
www.bennadel.com/blog/328-Am-I-The-Only-One-Who-Likes-White-Space-In-My-ColdFusion-Code-.htm
:)
@Marc,
When I see too many lines of code in a row, I start to panic :) Having the white space is just a personal preference - it helps me think about each chunk of code a bit more independently.
You're not the only one who dislikes my style - Simon Free (with the support of many fans) actually create a IDE plugin that would strip out my excessive whitespace:
http://debenification.riaforge.org/
... get it, De-Ben-ification :D
Loving your posts on AngularJS Ben. These videos/blog posts are great!
I have a favor to ask though... can you please please please use a friendlier video component - html5, so i can watch without flash :)
Thanks!
Steve
Suicidal Plugins ... Nice.
Regarding Reformatting Code ...
Intellij IDEA :: CTRL+ALT+L
Reformat ad-hoc ... ;-)
@Steve,
Yeah, I really gotta figure out the video stuff. I just JING to record the videos; and I think if I upgrade to their pro account, they can do HTML5 videos. I'll look into that ASAP.
Wonderful post. Thanks!
@Dave,
Thank you, kind sir!
Thanks for your interesting in-depth AngularJS articles !
Would be nice to make more compact code though :)
this is supposedly an antipattern:
// Gather the ngRepeat'd DOM elements.
var values = $( "span.value" );
do you have a reason for intentionally using it despite the convention? (wrapping dom tags in $( - supposedly this is done by default/wondering if 'double' wrapping it is of any advantage(???)
Tia,
@Greg,
I don't think there is any double-wrapping. The "Span.value", in this case, is not the element associated with the directive - in which case, it *would* be double-wrapping. What I'm doing is actually locating the span.value matches lower-down in the DOM tree. Basically, I'm just querying the DOM via old-school jQuery.
That said, I have many times done this:
... that IS double-wrapping, and if there's code like that it's because I didn't realize that the element passed into the directive was already a jQuery/jQLite element. :)
@Ben Nadel
ironically, just read about it today - i don't know why, but the example code here doesn't get evaluated in the later jquery or angularjs (jquery 2.x.x && angularjs 1.2.x)
is there a paradigm shift at a conventional level? something seems to be different enough for it to not be recognizing the setup.
so far, been scoping out the ng___ commands - nothing looks different enough to break it so far.
would appreciate a clue if you know though.
thanks again,
<g>
thanks this is really useful.