params.json

{"name":"AngularJS - Perceived Performance","tagline":"Directives for measuring and reporting perceived page performance","body":"\r\n##Page Load vs Perceived Page Load\r\n\r\n\r\nIn a traditional page, measuring the page performance is quite easy; a request is made, the server responds with some HTML and the browser renders it.  Done.\r\n\r\n![Traditional](http://farm3.staticflickr.com/2852/9727108341_c6081f9fb3_o.png)\r\n\r\nA lot of the rendering logic is taken care of as part of the server processing and so looking at `Window Load` and `DOMContentReady` are good indicators of page performance.\r\n\r\nIn a Single Page Application, things get trickier.  The `Window Load` is only the beginning - that's when the JavaScript has been delivered to the browser, at which point the client-side logic - all the real work - kicks in and begins rendering the page, making API calls and setting up listeners, events, etc.\r\n\r\n![SPA](http://farm8.staticflickr.com/7393/9727108327_91103f0d03_o.png)\r\n\r\nThe DOM is then continuously manipulated as part of user interaction or monitoring, polling and other events. As you can see, the traditional definition of a page being 'done' doesn't apply here.\r\n\r\nThe *perceived* page performance is how long the user thinks the major elements of the page took to load. By definition it is highly subjective - some users may think that the page is loaded just because the initial furniture appears.  But for most users this will be the parts of the page they consider most important.  \r\n\r\nTaking GMail as an example, most users will consider the page ready when the list of emails appear.  Whether or not the social tabs, filters, navigation or GTalk appears is less important.  \r\n\r\n![gmail](http://farm6.staticflickr.com/5520/9756473461_815bba6b5b_o.png)\r\n\r\nSimilarly, on a news website, the title and body of the news article matter the most.  Related articles and featured stories aren't that important, but top stories may matter.\r\n\r\n![bbc](http://farm6.staticflickr.com/5329/9756789024_f61b0d57f4_o.png)\r\n\r\nThe images above are just examples with arbitrarily assigned regions of importance.  The point here is, the definition of page done has to be defined on a per-case basis.  The most common definition is usually something like *\"The page is done when this particular div is filled with content\"* - indicating that the page loaded, an API call was made and the contents were rendered. On a heavier page, this would be when three or four divs have all been filled with content.  You could even choose to ignore certain parts of the page as being less important.\r\n\r\n\r\n##So how do we measure perceived page performance?\r\n\r\nThe *perceived* page load is when all of the important dynamic parts of the page have been filled.  This requires the developers to agree upon what the most important parts are, and to programmatically indicate when the specific portions are done.  It's an inexact science and the results will vary from user to user due to machine specs, network latency and other environmental factors, but you get a good idea of the timings involved and what users are actually experiencing.  \r\n\r\nBecause this is a client side operation, a few components are required:\r\n\r\n1. An indicator placed on various parts of the page to watch that specific portion of the page (eg. article body, top articles, but not header or featured stories).\r\n2. A listener which waits to be informed by all of the indicators; internally the listener can set up various timers as necessary.\r\n3. A beacon which the listener can send the aggregate information to once it is satisfied that all of the indicators have reported to it.  This beacon usually takes the form of an empty image, with timings passed in the querystring.\r\n\r\n        /beacon.png?content=3913&name=ArticleView&initial=1011\r\n    \r\n    The above means it took the ArticleView page 1011 milliseconds for its *initial* load and 3913 milliseconds to load the actual *content* (the perceived load time).\r\n\r\n4. The beacon requests will be stored in your web server logs, and a log parsing application (eg. logster) can retrospectively process it, grab the information and store it your aggregating service (eg. graphite).\r\n\r\n\r\n![components](http://farm8.staticflickr.com/7417/9758863125_b186c911d3_o.png)\r\n\r\n\r\n##Using the performance directives\r\n\r\nThe listener shown above is the `performance` directive.  Place this attribute at the beginning of your angular view.  \r\n\r\n    <div performance=\"PageName\" performance-beacon=\"/sample/img/beacon.png\">\r\n    \r\nThe `performance-beacon` indicates where the HTTP request should go when perceived page load is complete.\r\n\r\nThe watchers above are the `performance-loaded` directives.  Place these attributes anywhere within the view and set its value to an object on the `$scope`.  For example, you can do this\r\n\r\n    performance-loaded=\"ProductsFromAPI\"\r\n    \r\nThis directive will watch the `$scope.ProductsFromAPI` object and mark loading as done when this object contains a value.  You can control this further by using an object just for this directive:\r\n\r\n    performance-loaded=\"Loaded\"\r\n    \r\nAnd in your controller, only set `$scope.Loaded = true` when you feel that all the processing is complete.  This is useful when your controller makes multiple API calls and you need to wait for all of them to complete before indicating that loading is complete.\r\n\r\n \r\nEnsure that the `performance loaded` directives sit within the scope of the `performance` directive.  In other words, the `performance-loaded` directives should be in the same controller as `performance` or in a 'sub-controller' inside it.  \r\n\r\n**Correct:**\r\n\r\n    <div ng-controller=\"MyController\" performance=\"PageName\">\r\n        <div performance-loaded=\"ProductsFromAPI\">\r\n    </div>\r\n    \r\n**Correct:**\r\n\r\n    <div ng-controller=\"MyController\" performance=\"PageName\">\r\n        <div ng-controller=\"SomeOtherController\" performance-loaded=\"ProductsFromAPI\">\r\n    </div>\r\n\r\n**Incorrect:**\r\n\r\n    <div ng-controller=\"MyController\" performance=\"PageName\">\r\n        ....\r\n    </div>\r\n    <div performance-loaded=\"ProductsFromAPI\">\r\n\r\n**Incorrect:**\r\n\r\n    <div ng-controller=\"MyController\" performance=\"PageName\">\r\n        ....\r\n    </div>\r\n    <div ng-controller=\"SomeOtherController\" performance-loaded=\"ProductsFromAPI\">\r\n\r\n\r\n\r\n## Demo/Code\r\n\r\nSee [this page](http://code.mendhak.com/angular-performance/sample/) for a demo.  Be sure to open your networks tab or Fiddler to see the beacon request.\r\n\r\n![network tab](http://farm8.staticflickr.com/7432/9759419411_4bddff429b_o.png)\r\n\r\nLook at [index.html](https://github.com/mendhak/angular-performance/blob/master/sample/index.html) and [controllers.js](https://github.com/mendhak/angular-performance/blob/master/sample/js/controllers.js) to see how it's done.\r\n\r\nYou can use [angular-performance.js](https://raw.github.com/mendhak/angular-performance/master/src/angular-performance.js) or its [minified version](https://raw.github.com/mendhak/angular-performance/master/build/angular-performance.min.js).\r\n\r\n\r\n## License\r\n\r\n[MIT License](https://github.com/mendhak/angular-performance/blob/master/LICENSE)\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}