ng-include

[andersonlfurlan]

@johnpapa Why you don't recommend use of the directives instead ng-include in your guide?
I think a best pratice use directives.

@alsfurlan I completely agree with you regarding the use of custom directives over ng-include. When using ng-include, you are forced to spread and duplicate urls to templates throughout your code. This is solved by using a custom directive where the url can be described as a templateUrl in a single location.

/* avoid */

// index.html
<div ng-include="/src/feature/feature.html"></div>

/* recommended */

// index.html
<div feature></div>

// src/feature/feature.directive.js
(function() {

    angular
        .module("feature")
        .directive("abcFeature", abcFeature);

    function abcFeature() {
        var directive = {
            restrict: "A",
            templateUrl: "/src/feature/feature.html"
        }
        return directive;
    }

})();

[andersonlfurlan]

@jteppinette Yeah! This is why I ask to @johnpapa. I think with your code is very relevant and could be included in him angular style guide. Ng-include remeber languages like PHP e Java and it seems, to me, a bad practice.

[dietergeerts]

And what do you do when you want to switch out the view for a controller/directive? View and ViewModel should be separated and there are situations where I want another view for the same ViewModel. For this, ng-include is really handy, as you can define the viewmodel (controller) and view that has to be combined. A directive should be used for small components that doesn't influence the actual view, but work on it.

Also, using directives messes up Angular's form behaviours and you aren't being able to have correct validation anymore...

@dietergeerts I believe the tool you are looking for in this case is a router. In your particular situation, you can define a parent route with a controller and then you can create children of that route with or without their own individual templates, controllers, urls, etc...

Thank you for joining the conversation. We need as much input as possible to create a great styleguide.

[andersonlfurlan]

I agree with @jteppinette.

ng-include seems only one not to let the html at all on the same page, which makes no sense at all. It will be a reusable HTML, uses a directive, if you have other logical use a directive.

Not least because it does not seem coherent keep doing this with many other features in angular.

If you change the path of your HTML file will break the view. Millions of places I can have my ng-include, millions of places to refactor. A directive only in one spot, on a route only in one location.

Do not you want the big HTML? Think of componentization and division of responsibilities between controller, do not use ng-include.

[dietergeerts]

@jteppinette , no, for many situations the router can't be used. If you have a list of items for example, I can now use ng-include to tell how they must be represented, as it can be different depending on where this list is. The controller to set the item behaviour can also be set in that ng-include. This has nothing to do with router. If you think it does, than please provide such an example.

@dietergeerts In the situation you have depicted, the best course of action would be utilizing a directive with a template that used 'ng-if' to switch between different sets of inner html based on an isolated scope variable that is passed into the directive.

I am currently on my phone, but when I reach a computer, I will provide proper examples.

[andersonlfurlan]

@dietergeerts In your case, for items a directive should be created. It is the best way to do. You can see in several angularjs books including, in your example, a list of items, most of them create directive for item individually. The controller for setting behavior, in this case, must be set in the directive. "ng-include" is an amateur way to do it, I think.
And then again, as you would treat a case where moves your html file location? Refactor everywhere?

[andersonlfurlan]

@dietergeerts And as well remembered by @jteppinette, has the scope that can treat it.

[johnpapa]

i dont personally use ng-include anymore. i use a directive for even basic footers and headers. but its not a bad practice to use ng-include.

might be worth adding to the guide, but i would be interested in hearing about more use cases for and against

[andersonlfurlan]

@johnpapa Of course not, I think just an elegant way to do what ng-include do: directive. Ok, let the people discuss. 👍

[johnpapa]

just a few stray thoughts on both sides, nd in between...

ng-include is dirt simple. thats a big plus. also very obvious what it is doing.

harder to test , yeah, i think directive is easier.

if you use ng-include you could add controller in the view directly, which is different than the style of putting the routes and controllers together. not good or bad, just different.

directives are a pain .... ugly with their DDO. but using them for a simple template is pretty easy.

Statement

---

I am in support of adding a directive over ng-include rule to the angular style guide.

Positive & Negatives

---

To demonstrate my thoughts clearly, I have created the following list of positives and negatives:

Positives

• Dry: When working on large code bases that make use of ng-include simple code-reorganization requires changing urls throughout the code base.
• Modularization, Cohesion, & Coupling: When I have seen developers make use of ng-include it is typically accompanied by very high coupling and low cohesion of their controllers. The simple act of using a directive to supply a template encourages the developer to also place the templates business logic inside a separate template or service that is accompanied by that specific directive.
• Testing: The practice of testing directives has been repeatedly tried and documented. The use of directives over ng-include is clearly the winner in this regard.
• Naming: Directives provide readers of software a clear way to identify the functionality of an element or attribute directive through its element or attribute name. This is in comparison to the use of ng-include where the reader must parse the url to identify its functionality.

Negatives

• Ease of Use: I will not argue that the use of ng-include is easier. However, I tend to reference this quote in times of internal debate in regards to easy vs hard.

  Bad habits are like a comfortable bed, easy to get into, but hard to get out of.
  — Anonymous

References

---

• Google Group: Ng-Include vs. Directives
• Bannadel: Ng-Include vs. Directives
• Stack Overflow: Ng-Include vs. Directives
• Nathan Claire: Don't Fear Directives
• LinkedIn: Ng-Include vs. Directives

Discussion Contributors

---

• @johnpapa
• @alsfurlan
• @dietergeerts

[wardbell]

I will speak in favor of ng-include as a valuable alternative to creating a custom directive.

Pros

• dirt simple
• easy to read and follow
• no crazy extra directive boiler plate
• easy to test (prove to me it isn't)
• ultra DRY ... if you only include it once :-)
• easy to bind to a property of the parent view controller; such a property can toggle the template (e.g., List View, Card View, Icon View).
• easy to find and relocate if you move the view (no harder than inside the directive) ... if you only use it once.

Cons

• not suitable for repeated content such as headers and footers (for reasons others mention)
• what it means may not be obvious if you pick a terrible template name (same problem if you pick a terrible directive name)

The Ideal ng-include Scenario:

ng-include is perfect if you're referencing the included view template exactly once. I do that a lot.

I break up a gigantic, incomprehensible view into a master view and sub-views. Sub-views may have their own controllers but they often just inherit the master view controller.

These sub-views won't be seen anywhere else except in the master view. I don't want you to navigate to them or to any particular combination of sub-views. The master view and sub-view combinations are determined entirely by the master view's controller and whatever state is passed in or preserved from a prior visit.

When not to use ng-include

When the view will appear in many places (e.g., headers and footers). Such intentionally re-usable visual components deserve the effort necessary to make them directives.

My opinion

I think creating a one-off directive is a waste of effort, complicates understanding, is a burden to maintain, and is an excess of architectural zealotry.

In general, I do not worrying about DRY nor go through the gyrations of abstracting into multiple moving parts until I've used the darn thing more than once.

The @jteppinette example (early in this thread) of what to avoid and what to do illustrates my point perfectly.

I would always prefer the one line, <div ng-include="/src/feature/feature.html"></div>, to the 16 lines of madness if I am only ever going to see feature.html in one place.

OTOH, the @jteppinette example makes perfect sense if the view is re-usable.

@wardbell Thank you joining the conversation! Your expertise will definitely come in handy.

I completely agree with the points you have made, and I believe that we could point out to readers that both approaches have merit when used in the proper context.

Ng-Include should be used when the template is only being injected a single time.

Custom Directives should be used when the component is being used in multiple places.