{"id":68609,"date":"2016-10-06T13:56:56","date_gmt":"2016-10-06T13:56:56","guid":{"rendered":"https:\/\/www.simple-talk.com\/?p=68609"},"modified":"2022-05-24T20:06:32","modified_gmt":"2022-05-24T20:06:32","slug":"4-keys-clean-angular-implementation","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/development\/dotnet-development\/4-keys-clean-angular-implementation\/","title":{"rendered":"4 Keys to a Clean Angular Implementation"},"content":{"rendered":"
    \n
  1. Why a template engine?<\/a><\/li>\n
  2. Why separate concerns?<\/a><\/li>\n
  3. Rules of separation<\/a><\/li>\n
  4. Well, maybe suggestions of separation<\/a>\n
      \n
    1. On modifying the model in the view<\/a><\/li>\n
    2. On accessing dependent data in the view<\/a><\/li>\n
    3. On using logical expressions in the view<\/a><\/li>\n
    4. On tailoring functions for the view<\/a><\/li>\n<\/ol>\n<\/li>\n
    5. Summary<\/a><\/li>\n<\/ol>\n

      I have recently been thinking about fundamental best practices for separation of concerns in Angular. Separation of concerns is not a new topic in software development, by any means. It certainly goes back farther, but let\u2019s \u201conly\u201d go back to 2004 to start honing in on a useful perspective for modern web development. That year saw the publication of Terence Parr\u2019s seminal paper, Enforcing Strict Model-View Separation in Template Engines<\/a>, published in ACM\u2019s Proceedings of the 13th International World Wide Web Conference<\/a>. As far as web technologies, so much has changed in those intervening 12 years, yet much of what Parr reflects upon is still useful today. But you could discern that just from the title. We still use the model-view-controller (MVC) paradigm, and its variants, as a matter of course to develop cleaner code today. And we certainly use template engines, Angular being among the most popular today.<\/p>\n

      Why a Template Engine?<\/h2>\n

      In the earliest days of the web, web pages were static. A web page existed in a constant form, as a file on a disk, and was served up, byte for byte identical each time to every user. Very quickly, though, developers realized dynamic web pages were necessary in order to do anything useful (other than publishing a book online, perhaps). The earliest dynamic web pages were generated manually by server side code, notably by Perl and later by Java. But the task of generating HTML by writing raw strings is terribly tedious, time-consuming, and error-prone. So along came the notion of a template engine<\/em>. The idea was that you, the developer, provide an HTML file (a template<\/em>) that contains place holders to be filled in at runtime by the template engine. Even with a very simple template language you could allow the user to fill in anything from individual values to complex tables. The template engine marries the template written in your template language with the necessary data to produce a finished web page that is sent to the client browser for rendering. Template engines provided a useful way, then, to separate your data from the presentation of that data.<\/p>\n

      Why Separate Concerns?<\/h2>\n

      It has been well established for quite a long time that separation of concerns in software design is a good thing. Parr\u2019s paper itemizes the key reasons, shown below with my commentary, though you have likely seen variations of this list before:<\/p>\n

        \n
      1. Encapsulation<\/strong>: the view is in the template; the business logic is in the model \/ controller.<\/li>\n
      2. Clarity<\/strong>: A template is written in HTML (with the slight addition of some notation for place holders) rather than code, so it is a presentation-layer document rather than \u201csource code\u201d per se. And depending upon your choice of editor, you might even work with the template in a WYSIWYG designer.<\/li>\n
      3. Division of labor:<\/strong> designers who are good at user interfaces (user experience, usability, and so forth) could create templates, while developers who are good at coding could write the code.<\/li>\n
      4. Component reuse<\/strong>: a template could include other templates, so you could re-use discrete pieces (e.g. for navigation bars, search boxes, etc.)<\/li>\n
      5. Single point of change\/maintenance\/interchangeable views: <\/strong>
        \nWhen you want to change how data is displayed or manipulated at the UI level\u2014without changing any underlying functionality\u2014you only need to edit the template.<\/li>\n<\/ol>\n

        Actually, all of these advantages are really quite interrelated, suggesting that it is more productive to compartmentalize the view or UI layer just as you compartmentalize all other aspects of your software design. Parr\u2019s final consideration in this list is security, though I\u2019m not convinced that separation of concerns here leads to improved security; there are still plenty of things you can do to weaken your defenses!<\/p>\n

        Rules of Separation<\/h2>\n

        Parr suggests that a good template engine enforces strict separation of the model and the view. Specifically, the view should not<\/em><\/strong>:<\/p>\n

          \n
        1. modify the model<\/li>\n
        2. perform computations upon dependent data (e.g. $price * .90<\/code>)<\/li>\n
        3. compare dependent data (e.g. $bloodPressure < 120<\/code>)<\/li>\n
        4. make data type assumptions<\/li>\n
        5. get any layout information from the data<\/li>\n<\/ol>\n

          At the time he wrote his paper, Parr found that, among the dozen or so template engines he considered, the entanglement index<\/em> \u2013 the number of rules that a template engine violates \u2013 is either 1 or 5. Two interesting observations here. First, it is not<\/em> possible to have an index of 0, because rule 5 cannot be enforced (e.g. is a value of \u201cRed\u201d a man\u2019s name or a color to render?). Second, there was no middle ground (template engines ranking 2, 3, or 4); apparently once you open the barn door, so to speak, everything floods in! Parr goes on to suggest that enforcement<\/em> of separation (by the template engine) is much preferred to encouragement<\/em> of separation (i.e. by convention).<\/p>\n

          Well, Maybe Suggestions of Separation<\/h2>\n

          And here is where I feel that current web standards require a different approach. First, I agree in principle that enforcement is better than encouragement. For example, I would not want my compiler to suggest<\/em> that I should fix compiler errors\u2014I want the compiler to fail if there are serious errors. But there are a plethora of other processors in a build sequence that emit red flags yet do not<\/em> cause an aborted compile: ReSharper warnings, JSHint warnings, CSS warnings, even code warnings (as opposed to errors) from the compiler itself. In other words, encouragement is not unprecedented and is, in fact, widespread.<\/p>\n

          Besides those machine-recognizable issues, which could<\/em> be enforced, there are a variety of code issues that can only<\/em> be dealt with by encouragement. Here I\u2019m speaking of generally accepted best practices as well as code conventions of your specific team and\/or company; which brings us squarely back to web development and more specifically to the framework I want to focus on here, Angular. Angular is a template engine and its entanglement index is 5. It is so powerful and flexible, you can do anything you darn well please. But that does not mean you should<\/em>!<\/p>\n

          The remainder of this article, then, provides my recommended and encouraged best practices for Angular and specifically focuses on accessing the model in the view with respect to Parr\u2019s first three rules.<\/p>\n

          On modifying the model in the view<\/h3>\n

          Say you have a button to switch your web app to edit mode:<\/p>\n

          <<\/span>button<\/span> ng-click<\/span>=\"<\/span>EditMode =<\/span> true\"><\/span>Edit<\/<\/span>button<\/span>><\/span><\/pre>\n
          Elsewhere in your template you react to that variable\u2014here we hide the \u2018delete<\/em>\u2019 button if we\u2019re in edit mode:<\/p>\n
          <<\/span>a<\/span> ng-click<\/span>=\"<\/span>Delete<\/span>()\"<\/span> ng-hide<\/span>=\"<\/span>EditMode<\/span>\"><\/span>Delete<<\/span>\/a<\/span>><\/span><\/pre>\n
          Of course, we\u2019ll need a \u2018cancel<\/em>\u2019 button that reveals itself during edit mode, and upon being clicked, turns off edit mode.<\/p>\n
          <<\/span>button<\/span> ng-show<\/span>=\"<\/span>EditMode<\/span>\"<\/span> ng-click<\/span>=\"<\/span>EditMode =<\/span> false\"><\/span>Cancel<\/<\/span>button<\/span>><\/span><\/pre>\n
          That seems clean and simple. Indeed, some might argue it is preferable to manipulate the model (EditMode) in the view because it is all self-contained in the view. While that is an advantage, it is outweighed by the disadvantage of (a) having less testable code (because you do not really have any way to test that bit of code in the view), and (b) violating rule 1 (modifying the model in the view), which weakens separation of concerns.<\/p>\n
          Furthermore, we need one more button to save the work done in edit mode.<\/p>\n
          <<\/span>button<\/span> ng-show<\/span>=\"<\/span>EditMode<\/span>\"<\/span> ng-click<\/span>=\"<\/span>EditMode<\/span> = false;<\/span> SaveItem<\/span>()\"><\/span>Save<\/<\/span>button<\/span>><\/span>\r\n<\/pre>\n
          Whew, did you catch that foul odor? Quite a code smell there\u2014putting multiple JavaScript statements in an attribute! Yes, doing that allowed maintaining the EditMode model data completely in the view, but that\u2019s not really such a good thing after all, as just described above. I would suggest that button should contain just a single method call upon click:<\/p>\n
          <<\/span>button<\/span> ng-show<\/span>=\"<\/span>EditMode<\/span>\"<\/span> ng-click<\/span>=\"<\/span>SaveItem<\/span>()\"><\/span>Save<\/<\/span>button<\/span>><\/span>\r\n<\/pre>\n
          And then the code-behind function should be, in part:<\/p>\n
          $scope.SaveItem =<\/span> function<\/span> () {\r\n\t$scope.EditMode = false<\/span>;\r\n\t\/\/ other code to save item here...\r\n}\r\n<\/pre>\n
          Similarly, I would advocate that the button to enter edit mode should be changed to eliminate direct manipulation of the model in the view as well:<\/p>\n
          <<\/span>button<\/span> ng-show<\/span>=\"<\/span>EditMode<\/span>\"<\/span> ng-click<\/span>=\"<\/span>BeginEditMode()<\/span>\"><\/span>Edit<\/<\/span>button<\/span>><\/span><\/pre>\n
          With the corresponding code in the controller:<\/p>\n
          $scope.BeginEditMode<\/span> = function<\/span> () {\r\n\t$scope.EditMode = true<\/span>;\r\n}\r\n<\/pre>\n
          So, by using methods to delegate model manipulations to the controller, we have eliminated any direct manipulation of the model in the view. This means you can then write unit tests for your controller code. Moreover, with this separation you have now encapsulated your business logic in the controller, leaving the developers free to rename the EditMode<\/strong> variable should they decide on a better name down the road. Or, should the need arise, they could change what it means to enter and leave edit mode without necessarily needing any changes in the view.<\/p>\n
          Note, though, that Parr\u2019s rule 1 regarding no model manipulation in the view applied to direct or indirect<\/em> manipulation; he considered that it was just as bad to call controller methods to manipulate the model. At that time, any such method calls were in the global namespace so, yes, that would be reasonably bad. But with Angular, you have much more fine-grained control, calling methods on a specific controller, so encapsulation saves the day here, in my opinion. Like any good library API, your controller should expose just sufficient methods to the view for the view to be effective and accomplish what it needs to do.<\/p>\n
          So I\u2019m suggesting the following best practice:<\/p>\n
          \n
          Guideline #1: Do not directly<\/strong> modify the model in the view; 
          \nuse functions on the controller<\/p>\n<\/div>\n
          On accessing dependent data in the view<\/h3>\n
          Consider this Angular fragment:<\/p>\n
          <<\/span>span<\/span> ng-if<\/span>=\"<\/span>ContentType<\/span> == 'Simple'<\/span>\"><\/span><\/pre>\n
          That\u2019s perfectly valid, yet quite ill-advised. Because Angular lets you use any JavaScript that you please, it is impossible to prevent this type of construct; we must rely on encouraging your offending colleague, perhaps adding some teaching and maybe some cajoling. (Oh, unless you<\/em> wrote that fragment in the view\u2026).<\/p>\n
          So why is this bad? First, the dependent data\u2014the string \u201cSimple\u201d in this case\u2014is part of your business domain. It has no business (pun intended!) being here in the view. What if your marketing guy decides to dress up the product a bit and change the \u201cSimple\u201d designation to \u201cSnazzy\u201d? Then you have to modify both the code and<\/em> the view! That\u2019s bad; you should only<\/em> have to modify the code (your store of product types) somewhere on the backend.<\/p>\n
          Second, what if the product owner wants to adapt the product to a new potential client, and needs that span to be revealed for two<\/em> content types? Again, you have to modify the view for a change in business logic! If instead the span was defined like this:<\/p>\n
          <<\/span>span<\/span> ng-if<\/span>=\"<\/span>IsSelected(<\/span>ContentType<\/span>)<\/span>\"><\/span><\/pre>\n
          Then you could manage the controller code with a function like that shown next, where the ContentTypeList could contain a single element, as the current version of your product uses, or could contain two elements for the new prospective client:<\/p>\n
          $scope.IsSelected = function<\/span> (ContentType) {\r\n    return<\/span> ContentTypeList.indexOf(ContentType) >= 0;\r\n}\r\n<\/pre>\n
          The above showed that a magic string in the view made it quite brittle. Similarly, you do not<\/em> want to use computation operators in the view with magic values<\/em>. Example to show the calculated value of a 6% tax to the user:<\/p>\n
          <<\/span>span<\/span>>Tax: {{Price<\/span> * .06}}<\/<\/span>span><\/pre>\n
          A hard-coded tax rate has no business being in the view. It might change for many reasons: your company relocates, your municipality changes its tax rate, you expand to online operations which uses its own peculiar tax rules, etc.<\/p>\n
          Thus, whether it is a comparison with dependent data (Parr\u2019s rule 3) or a computation with dependent data (Parr\u2019s rule 2), the idea is the same, hence my lumping the two rules together.<\/p>\n
          \n
          Guideline #2: Avoid magic numbers, magic strings, etc. especially in the view.<\/p>\n<\/div>\n
          On using logical expressions in the view<\/h3>\n
          Here is a typical Angular expression to dynamically set the class name of an element based on several criteria. This sets the class attribute to include \u201cmid-range\u201d if one property is not null or another not empty:<\/p>\n
          ng-class<\/span>=\"<\/span>{ 'mid-range'<\/span>:Item.LabelOverride<\/span> !== null<\/span> || Item.Description<\/span> !== ''<\/span> }\"<\/span><\/pre>\n
          At first glance, that is reasonable-looking enough. But if you consider for a moment, you\u2019ll see that each term of the expression is using a comparison operator, so each by itself would, by our previous guideline, be less than ideal. So let\u2019s use functions instead; is this better?<\/p>\n
          ng-class<\/span>=\"<\/span>{ 'mid-range'<\/span>:OverrideIsNotNull(<\/span>Item<\/span>)<\/span> || DescriptionIsNotEmpty(<\/span>Item<\/span>)<\/span> }\"<\/span><\/pre>\n
          Well, that follows guideline #2 by the letter of the law, but not quite the spirit. Those functions are still tied very closely to implementation details rather than usage, so still a bit of a code smell. Something more like this abstracts away those implementation details:<\/p>\n
          ng-class<\/span>=\"<\/span>{ 'mid-range'<\/span>:IsOverrideValid(<\/span>Item<\/span>)<\/span> || IsDescriptionValid(<\/span>Item<\/span>)<\/span> }\"<\/span><\/pre>\n
          It defers the interpretation of valid<\/em> to the code-behind, again for similar reasons as those discussed previously. But then there are still two terms connected with a disjunction. It probably will not surprise you that I claim that such logical operators, too, should be avoided. Using this instead:<\/p>\n
          ng-class<\/span>=\"<\/span>{ 'mid-range'<\/span>:IsValid(<\/span>Item<\/span>)<\/span> }\"<\/span><\/pre>\n
          \u2026allows the backend the flexibility to update the single meaning of valid<\/em> as business needs evolve.<\/p>\n
          Furthermore, the more terms that are joined with logical operators, the more foul is the \u2018code smell\u2019. I have seen instances with many terms in the expression, here represented symbolically:<\/p>\n
          ( (A || B) && (C || D) && (E || F) && (G || H) )<\/span><\/pre>\n
          The pure wave of foul code stench from that expression used in the view should reach you even through your internet connection!<\/p>\n
          It is important to note what I am not<\/em> saying here as well. If you carry this argument farther, you could say that the view should never<\/em> reference properties on the scope except for display purposes. However, I think that this is going past the point of diminishing returns: That is, instead of this property access:<\/p>\n
          <<\/span>span<\/span> ng-if<\/span>=\"WorkIsComplete\"><\/span><\/pre>\n
          \u2026you could use a function on the scope:<\/p>\n
          <<\/span>span<\/span> ng-if<\/span>=\"WorkIsCompleteFunction()\"><\/span><\/pre>\n
          \u2026that supplies that self-same property like this:<\/p>\n
          $scope. WorkIsCompleteFunction = function<\/span> () {\r\n    return<\/span> WorkIsComplete;\r\n}\r\n<\/pre>\n
          But here, the advantage of single property encapsulation is outweighed by the disadvantage of the extra overhead and extra code in this instance.<\/p>\n
          \n
          Guideline #3: Eschew operators of any kind (arithmetic, comparison, logical) in the view; use functions on the controller.<\/p>\n<\/div>\n
          On tailoring functions for the view<\/h3>\n
          Here is a loop in Angular that generates a table with the HTML whittled down to show just the relevant bits: each row will have a button, to perform some type of optimization, that requires four parameters.<\/p>\n
          <<\/span>div<\/span> ng-repeat<\/span>=\"<\/span>usage<\/span> in<\/span> response.Usages<\/span>\"<\/span>>\r\n\u00a0\u00a0<tr<\/span>>\r\n\u00a0\u00a0\u00a0\u00a0<td<\/span>>\r\n\u00a0\u00a0\u00a0\u00a0<\u00a0\u00a0button<\/span> ng-click<\/span>=\"Optimize(usage,NumOps,Colors,Score<\/span>)\"><\/span>Optimize<\/<\/span>button<\/span>><\/span>\r\n\u00a0\u00a0\u00a0\u00a0<\/td<\/span>>\r\n\u00a0\u00a0<\/tr<\/span>>\r\n<\/div<\/span>><\/span>\r\n<\/pre>\n
          There are no magic strings, there are no operators of any kind; it uses properties in the scope (NumOps, Colors, and Score) but does not do any operations on them in the view. Everything is in a function so that the function can be unit-tested thoroughly in the code-behind\u2026 but since we\u2019re here talking about it, what is wrong with it?<\/p>\n
          The short answer: too many parameters<\/em>. You will hear a typical guideline for functions or methods that they should have no more than seven parameters, or perhaps no more than four\u2026 I submit that for a function exposed to the view (i.e. defined on the scope), it should be exactly one<\/em><\/strong> parameter if you are in a loop (ng-repeat) or zero<\/em><\/strong> parameters otherwise!<\/p>\n
          Your immediate reaction might be that that is totally impractical. But remember the context\u2014the Angular scope. The code-behind in the controller already has encapsulated access to all those scope properties (NumOps, Colors, and Score) without the view having to explicitly pass them in, or pass them back<\/em>, to be more accurate. The only thing the controller does not have is a notion of which item in the loop is current so you need to provide that. Thus, the above code fragment should just be this:<\/p>\n
          <div<\/span> ng-repeat<\/span>=\"usage in<\/span> response.Usages<\/span>\"<\/span>>\r\n\u00a0\u00a0<tr<\/span>>\r\n\u00a0\u00a0\u00a0\u00a0<td<\/span>>\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<button<\/span> ng-click<\/span>=\"Optimize(usage<\/span>)\"><\/span>Optimize<\/<\/span>button<\/span>><\/span>\r\n\u00a0\u00a0\u00a0\u00a0<\/td<\/span>>\r\n\u00a0\u00a0<\/tr<\/span>>\r\n<\/div<\/span>><\/span>\r\n<\/pre>\n
          \n
          Guideline #4: Be stingy with adding arguments to a function exposed to the view.<\/p>\n<\/div>\n
          Summary<\/h2>\n
          With the level of interactivity in a modern web page, it is unrealistic to achieve complete separation using the MVC paradigm; and, indeed, it is crucial for the view to be able to manipulate the model, but only via a carefully crafted API that is the \u201cpublic\u201d scope of the Angular controller. More important, though, is to perform all<\/em> business logic in the code-behind as directed by the controller or its delegate. The view should only<\/em> use exposed model properties for either display or standalone logic (i.e. a single property with no operators). All operations on the model (assignments, computations, comparisons, etc.) should be done in the controller:<\/p>\n
            \n
          1. Modify all model properties in the controller rather than the view; let the view have access to the capability via controller functions.<\/li>\n
          2. Keep all magic values (if you must have them at all) in the controller accessing them in the view via controller functions.<\/li>\n
          3. Evaluate all comparison, computation, and logical expressions in the controller, giving the view access to them via controller functions.<\/li>\n
          4. Pass to a controller function only what it does not already know: the loop parameter if in a loop, or no parameters at all if outside of a loop.<\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"
            Can there be true separation of concerns with MVC? Not entirely, especially when Angular’s templates allow you so much flexibility; but there is a great deal to be gained from following  guidelines to ensure that  all business logic is performed in the code-behind as directed by the controller or its delegate, and that all operations on the model are done in the controller: Michael Sorens explains the four essential guidelines for an easily-maintained  system.…<\/p>\n","protected":false},"author":221868,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[143538,146992],"tags":[],"coauthors":[6802],"class_list":["post-68609","post","type-post","status-publish","format-standard","hentry","category-dotnet-development","category-angular"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/68609","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/221868"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=68609"}],"version-history":[{"count":25,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/68609\/revisions"}],"predecessor-version":[{"id":85635,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/68609\/revisions\/85635"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=68609"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=68609"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=68609"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=68609"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}