Directives man! While the they're literally the entry point into angular development (you can't get going without ng-app), many people starting out with Angular are hesistant to write their own because of the complexity associated with them. But once that initial hurdle is crossed their value as reusable components becomes indispensible.
Occasionally a complicated component will come along, one that is naturally modeled by mutliple directives. Unlike stand alone directives these directives only make sense when grouped together. They collaborate. They are aware of each other and they need to communicate with each other. This post will discuss best practices for managing communication among collaborating directives and illustrate these practices with an example.
Lets explore a few ways to solve this problem. Imagine a scenario like this:
<component>
<subcomponent></subcomponent>
<another-subcomponent></another-subcomponent>
</component>
It's tempting to communicate via shared scopes. The component directive could expose an API by exporting functions and data on its scope. These are available to both subcomponent and another-subcomponent (assuming neither uses an isolate scope) and now both directives can communicate directly with the parent component directive. Component, however, cannot communicate directly with subcomponent or another-subcomponent becuase scopes represent a hierarchical relationship between parent and child. This relationship is implemented using prototypical inheritance, so children have access to data placed on the scope by the parent but not vice versa. For component to communicate with its children it has to find another way.
Similarly, subcomponent and another-subcomponent will have trouble communicating because they are siblings and scopes do not provide a method for sibling communication.
NOTE: which approach? trying to communicate using the limited communication you can do using scopes?
This approach does not appear to be ideal. Communication is limited, but there are a few other problems:
- Scopes are generally used to provide data to templates and coordinate events generated by user interaction with the view. Using them for inter-directive communication concerns overloads their responsibilities and is working against the framework.
- Isolated scopes are not available since data and communication is being routed through scopes.
- As component grows so too will the surface area of scope. It will become hard to maintain and reason about the implementation. Data placed on the scope by component may accidentally be masked by data placed on the scope by subcomonent or another-subcomponent.
For a more detailed discussion on scopes in angular, check out this article http://blog.carbonfive.com/2014/02/11/angularjs-scopes-an-introduction/
The inability to communicate directly between parent and child or between sibling directives often leads to the idea of using Angular's eventing system to facilitate communication. This is an improvement over the scope based solution in that it keeps the scope clean -- they're being used for their intended purpose, isolate scopes won't create problems, etc. But the eventing system has its own concerns: specifically eventing in angular is directed either up the scope hierarchy via $emit or down it via $broadcast. This means that a directives location in the document is important when it comes to sending the event. Many apps circumvent this by injecting $rootScope and only using $broadcast from there. Not only is the extra dependency a bit of a bummer but increasing dependency list sizes is usually an indication that something is amiss.
The biggest problem with this approach, conceptually at least, is that the collaborating directives are carrying on a private conversation in public. By using $broadcast, the event is delivered across the entire system and any directive can react to it. This can lead to uninteded consequences -- a generically named event triggers an unintended event handler. While that problem can be solved by naming conventions, this is a work around attempting to better target the event. $broadcast is best suited to situations where the listeners of an event are unknown by a component. This differs from the situation of collaborating directives; the consumers are well known to the component.
So how should these directives communicate? The answer is in the documentation for directives (https://docs.angularjs.org/guide/directive) although tucked away at the bottom of the page:
Obvious, right? Ok, maybe not. In order to understand it we will need to look at the directive definition object and the signature of the link function. Lets say we have a template that looks like this:Best Practice: use controller when you want to expose an API to other directives. Otherwise use link.
Obvious, right? Ok, maybe not. Taking a look at how a directive is defined will shed some light. Here is the example template from above again:
<component>
<subcomponent></subcomponent>
<another-subcomponent></another-subcomponent>
</component>
And here is the directive definition for component which specifies a controller:
module.directive('component', function() {
function ComponentController() {
}
ComponentController.prototype.doSomething = function() {
// ironically does nothing
}
return {
restrict: 'E',
controller: ComponentController,
scope: {}
};
});
And the directive definition for subcomponent:
module.directive('subcomponent', function() {
function link(scope, element, attrs, componentController) {
componentController.doSomething();
}
return {
restrict: 'E',
require: '^component',
link: link,
scope: {}
}
});
Here's how it hangs together:
- The component directive defines a controller class. The controller is instantiated each time the directive is encountered. It is instantiated before the directive's template is compiled so that the controller can initialize the scope if needed.
- The subcomponent directive requires the compoent controller via the require property. Controllers are required via the directive name, not the name of the controller class. The '^' indicates that Angular should look for the controller in parent directives.
- The link function receives the controller as its fourth argument.
Imagine a tool which shows annotations on an image. It will look something like this:
-- screenshot / embedded directive --
There are three main sections to this thing:
- the image viewer
- the control bar
- the annotation list
By default, annotations are not shown. The image viewer shows the image but no annotations. The annotation list is hidden. When the user shows annotations the image viewer overlays the annotations and the annotation list is shown. Annotations can be selected either by clicking on the visual representation in the image or by selecting the item from the list.