Angular JS Directive - complete background

Question

I am a rookie in angularJS learning about directives (and struggling a lot :)).

I am trying to understand a piece of angularJS code in the plunker by user tasseKATT for the stack overflow question regarding angular-ui-bootstrap.

I was hoping if anyone can explain this code fragment in more detail.

Specifically

How parsing and compilation happens in directives

How angular knows when to recompile directives ($watch - perhaps, if so how).

I checked the documentation for $parse but dont see any explanation on the service taking a function. What piece of information am I missing.

Also what is the

 (value || '').toString();

used for.

What are the properties compileHTML. Where can I see the documentation for the compile function explained in more detail than the one provided by AJS.

What is $$addBindingClass(tElement) and $$addBindingInfo.

Explain the function ngBindHtmlWatchAction

what is $sce.

The fragment from the directive is below

 app.directive('compileHtml', ['$sce', '$parse', '$compile',
  function($sce, $parse, $compile) {
    return {
      restrict: 'A',
      compile: function ngBindHtmlCompile(tElement, tAttrs) {
        var ngBindHtmlGetter = $parse(tAttrs.compileHtml);
        var ngBindHtmlWatch = $parse(tAttrs.compileHtml, function getStringValue(value) {
          return (value || '').toString();
        });
        $compile.$$addBindingClass(tElement);

        return function ngBindHtmlLink(scope, element, attr) {
          $compile.$$addBindingInfo(element, attr.compileHtml);

          scope.$watch(ngBindHtmlWatch, function ngBindHtmlWatchAction() {

            element.html($sce.trustAsHtml(ngBindHtmlGetter(scope)) || '');
            $compile(element.contents())(scope);
          });
        };
      }
    };
  }
]);

Answer 1

Disclaimer : First thing buddy, you are a rookie in angular and you are trying to understand directives using a very complicated directive. Maybe its better if you start with something a little less complicated :)

I will try to answer your many questions:

How parsing and compilation happens in directives: Angular knows which all directives are present, so when you write a name which matches one of the directive it compiles the html and link the directive.(I am trying to find a good blog for you to read on these cycles of directive, maybe this post will help)

How angular knows when to recompile directives ($watch - perhaps, if so how): angular doesnot recompile directives, a directive is only compiled once when angular encounters it for the first time. $watch is basically put on a variable, so whenever angularjs is applying the changes of the scope, it looks for that variable if it is changed.

$parse It is a way of adding angular to html. So if you directly append html to an element, it does not have angular like features. So we get the html, compile/parse it and then append to the element. Parsing is basically getting all the variables in the html and applying two way binding on those, plus replacing them with their values in controller.

Read this post.

Remember that compile/parse are always done against a scope variable, because variables defined inside the html are properties of the scope variables.

What is this (value || '').toString(); This is a common coding practce of js developers. This basically amounts to :

(value ? value : '').toString();

Why dont we use value directly like this

value.toString();

Because if the value is undefined or null, it does not have a toString function and it will throw an error.

So the coder is trying to check if the value is there, then convert the value to string otherwise, just put empty string(converting to string results empty string).

what is $sce? sce is a service, that comes in file angular-sanitize.js which is a part of angular bundle. When somebody tries to modify html to insert his link(malicious activity we call it), angular does not allow and treats his html as simple text.

But what if you want to add html, you pass your html to $sce service(injected in controller/directive etc) and the output is the html which you can insert into the view(this will come as html).

$$addBindingClass This is just to add "ng-binding" class to the element, so that you can see which element has a model created by angularjs.

$$addBindingInfo This is to add information to the element for debugging purpose. You can select the element in the inspector and run the following statement in console to get the scope information.

angular.element($0).scope(); //$0 means selected element

Here is a link that explains this thing better.