angular directives from scratch

Angular Directives

!

by: Christian Lilley about.me/xml @xmlilley

Demos Repo: github.com/xmlilley/ng-demos

What are Directives?

Fine. How about…5(-ish) words: Logic & Behavior For UI

“...a way to teach HTML new tricks.”

Anything in your app that touches DOM

Examples: event-handling, behavior management, template pre-processing & insertion, data-binding, ‘Collection Views’, UI Widgets, conditional display, i18n & localization, etc.

The only other Angular construct that really touches the DOM is:

Angular Expressions.

The rest of it should be in Directives. (Even the ng-view that executes your routing is simply a model-driven directive...)

Fine. How about…

Structurally speaking, a Directive is just a function that’s attached to an element.

But not just a function: a whole execution environment. Really, Directives are mini-applications.

You can think of them as little robotic pilots that live on your DOM elements & tell them what to do.

Fine. How about…

They can BYO DOM, or just be declared on inline DOM.

Fine. How about…

What AREN’T they?Directives.

Aren’t.

Just.

Where.

Your.

JQuery.

Goes!

Please,

God:

No.

I

BUT...

I

Moar

“The Superheroic

MVW framework.”

Angular isn’t just another way to

organize the same old UI code!!!

Opinionated Principles

1. Declarative, Model-Driven Behavior

Why Declarative?IMPERATIVE = YOUR PROBLEM

DECLARATIVE = SOMEBODY ELSE’S PROBLEM

Easier To Read, Maintain: Why scatter event-listeners across 100 linked JS files, then need to go search for them to find out what’s happening on an element.

Declarativeness ROCKSYou’re trying to find handlers for this element:

Well, where are the event-handlers? On ‘#1’? On ‘.B’? ‘.C’? On ‘button’? What if it’s on ‘parentDiv>:first-child’?

You can’t misunderstand what’s happening with declarative directives:

<button id=”1” class=”B C”></button>

<button md-action-handler></button>

Extending HTML…HTML is NOT a virgin bride or hothouse flower.

The Semantics Wars are over. HTML is a highly-abstracted, Object-Oriented language for app interfaces and for *presenting* documents. Docs themselves are increasingly stored in other formats, like markdown.

We’re not abandoning accessibility. But it’s not a binary choice, anyway.

Opinionated Principles

1. Declarative, Model-Driven Behavior

2. Modularity, Reusability across contexts: Write Once, Run Anywhere

ReusabilityIt’s all about context-awareness, data-binding & DI.

Directives know their own element and local scope.

You can pass additional data into directives as attributes, right on the element.

<div id="header_tabs"><a href="#/home" active-tab="1">HOME</a><a href="#/finance" active-tab="1">Finance</a><a href="#/hr" active-tab="1">Human Resources</a><a href="#/quarterly" active-tab="1">Quarterly</a>

</div>

AND...<div id="subnav_tabs"><a href="#/hr/pay" active-tab="2">Pay</a><a href="#/hr/benefits" active-tab="2">Benefits</a><a href="#/hr/help" active-tab="2">Help</a>

</div>

1. Declarative, Model-Driven Behavior

2. Modularity, Reusability across contexts: Write Once, Run Anywhere

3. Keep it Local

Opinionated Principles

No...

Yes: ‘Local’Sticks to a self-contained, modular scope, which understands its context: inside the directive, `element` is like `this`.

Uses messages, models to affect things elsewhere.

Easier to maintain, easier to read, easier to scale.

But the challenge to all that is:

My Awesome Website

Sweet Product

Product Description: Lorem ipsum dolor sit amet, consectetur adipiscing elit. In erat mauris, faucibus quis pharetra sit amet, pretium ac libero. Etiam vehicula eleifend bibendum. Morbi gravida metus ut sapien condimentum sodales mollis augue sodales. Vestibulum quis quam at sem placerat aliquet. Curabitur a felis at sapien ullamcorper fermentum. Mauris molestie arcu et lectus iaculis sit amet eleifend eros posuere. Fusce nec porta orci.!Integer vitae neque odio, a sollicitudin lorem. Aenean orci mauris, tristique luctus fermentum eu, feugiat vel massa. Fusce sem

$899.99 Buy Now!

Cart: 1 Item(s)

Clicking Here

Needs to Change

Things Here

Let’s Build Some!

Directive NamesAngular uses a convention borrowed from other JS projects: names in HTML are hyphenated...

while identifiers in the JS are camel-cased:

!

Expect Angular to do this conversion automatically. Don’t fight it.

.directive(‘sampleDirective’, function(){})

<sample-directive></sample-directive>

How are custom directives different from built-in?

They’re not.

At all.

No, really.

(Well, OK: they’re different in naming conventions: don’t use ‘ng-’ in your custom directives.)

CREATION.directive() is a method we call on an angular.module(), either at creation time or via reference, passing a name and a factory function

The factory will return either a function or an object containing a function and other settings

angular .module('moduleName', ['dependency1', 'dependency2']) .directive('directiveName', factoryFunction() {})

Factories(Note, when we talk about generic ‘factories’, we don’t mean $factory, which is an Angular implementation service.)

The factory pattern is all about Functional Programming: using basic Javascript functions to build and return either naiive objects or other functions.

What do We Do With That Factory Function?

Two Basic Options: Return a

Config Object or a ‘Linking Function’

You’ll See Later, But Ignore For Today:

Returning only the Link function

Link vs. Compile

Pre-Link vs. Post-Link

Using a Config Objectangular.module('moduleName').directive('sampleDirective', function(){ return { link: function(scope, element, attrs) { // this example binds a behavior to the // mouseenter event element.bind("mouseenter", function(){ ... do stuff after mouseenter ... } },

restrict: ‘E’, template: “<div>Hello, World!</div>” }})

Everything but `link` is optional.

Link Function Args .directive('sampleDirective', function(){ return { link: function(scope, element, attrs) { // this example binds a behavior to the // mouseenter event element.bind("mouseenter", function(){ ... do stuff after mouseenter ... } },

restrict: ‘E’, template: <div>Hello, World!</div> }})

Link Function Args3 standard params for a link function. (Plus optional 4th: controller.) They’re supplied as args by the directive function, if specified.

scope: whatever scope object is local

element: element declared on: `this`

attrs: an object containing the html attributes defined on the element, including the directive invocation itself

Supplied to the function not by name but in order. Call them whatever you want.

jqLite: your path to the DOM Angular will defer to JQuery, if present, but provides its own subset of JQuery for basic DOM tasks.

You can’t just use $(), nor find using selectors, unfortunately.

But all built-in `element` refs are already pre-wrapped in jqlite object

Chain methods as you normally would

addClass()after()append()attr()bind() children()clone()contents()css()data()eq()find() hasClass()html()next()on()

off() parent()prepend()prop()ready()remove()removeAttr()removeClass()removeData()replaceWith()text()toggleClass()triggerHandler() unbind() val()wrap()

Using jqLite (angular.element) .directive('sampleDirective', function(){ return { link: function(scope, element, attrs) { // this example binds a behavior to the // mouseenter event element.bind("mouseenter", function(){ ... do stuff after mouseenter ... } },

restrict: ‘E’, template: <div>Hello, World!</div> }})

$(‘selector’).bind(‘mouseenter’, function() {})

ACK! THPPPT!!! !

.bind() is ancient! !

Where’s .live() ?!? !

.on() ?!?

A Thought:If angular.element() / jqlite doesn’t support what you’re trying to do... ask yourself: why not?

Because they’re lazy bastards?

Not so much. Think about other options.

Go with the grain, and Angular will reward you.

Directive TemplatesTemplates can be stored as strings on the `template:` property

They can also be loaded from a file, using: `templateUrl: path/to/file/template.html’

Templates .directive('sampleDirective', function(){ return { link: function(scope, element, attrs) { // this example binds a behavior to the // mouseenter event element.bind("mouseenter", function(){ ... do stuff after mouseenter ... } },

restrict: ‘E’, template: ‘<div>Hello, World!</div>’//or:

templateUrl: ‘path/to/file.html’})

The Restrict Property .directive('sampleDirective', function(){ return { link: function(scope, element, attrs) { // this example binds a behavior to the // mouseenter event element.bind("mouseenter", function(){ ... do stuff after mouseenter ... } },

restrict: ‘E’, template: <div>Hello, World!</div> }})

The Restrict PropertyRemember that directives are re-usableSo, we can restrict the usage of a directive to (a) specific context(s), so that we don’t accidentally try to use it in a situation it wasn’t designed for:

‘E’ = Element‘A’ = Attribute‘C’ = Class‘M’ = Comment

Stack as a single string: ‘EACM’. Defaults to ‘A’.

The Replace PropertyBy default, a directive element will wrap the contents of a template. The `element` object will be the outer directive element.

To instead replace the directive element (and object) with the contents of the template, use {replace: true}

This is esp critical when declaring as an element...

Directives DEMO BREAKDOWN 1:

Enter-Leave

So, about that: Model-Driven & Local Directive Design...

Specifically, the Model-Driven

part...

Why Model-Driven?

After all, the imperative approach works fine...

...if you’re omniscient and precognitive.

... and you really, really like refactoring.

Comparative Click-Handlers: Imperative

“Do a whole bunch of stuff in response to that click. Remember all the things it should affect. Update all those things. Try hard (and fail) to do so without reading state from the UI. Try hard (and fail) to decompose these changes into reusable functions. Try hard (and fail) to make them declarative so I can easily understand and maintain what's happening."

Comparative Click-Handlers: Angular“Update some data, and/or send out a notification. Done.” (Everything else will happen in directives on the affected elements.)

In those other directives: “react to received events, or to data-changes. Change only what’s local to the element.”

How Can Directives React to Models?

With $watch!

Directives DEMO BREAKDOWN 2:

CLOCK

(haha! Get it? We’re going to use a clock to demo $watch...)

Keeping Directive Design Local

How Can Directives React to Stuff that

Happens Far, Far Away?Again, with models & $watch!

But sometimes, the inheritance chain isn’t a good solution. For those times...

Angular events! $on(), $emit(), $broadcast()

Advanced Topic: Inter-Scope Communication

Use $watch to monitor properties of local $scope or one it inherits from

That works great when you only need data to flow in one direction (up) and only on one branch of the tree.

What about when you need to go downwards, or sideways?

Or a whole bunch of places at once?

$rootScope

Main/Nav Controller

$scope

View 1 Controller

$scope

View 2 Controller

$scope

Directive A-1$scope

Directive B$scope

Directive A-2$scope

Directive C$scope

???

??????

???

???

Angular Events to The Rescue!!!

Just like how a ‘click’ event bubbles up through the DOM tree, you can $emit() an Angular event up the $scope tree, from any starting point.

Better than the DOM, you can also $broadcast() an event down the $scope tree.

$broadcast()-ing from $rootScope gets you the whole shebang.

Angular Events to The Rescue!!!

With events, there’s no need to laboriously climb your way up the $scope tree. You also eliminate the chance of getting the wrong scope.

You also get full de-coupling of a controller/directive from a particular place in your app. Use it anywhere, $broadcast() everywhere.

Angular Events to The Rescue!!!

And you don’t even need to predict who all the recipients will be. By sending: $rootScope.$broadcast(‘gameOver’) your whole app gets the information,

You can consume the event as many places as you like, with: $scope.$on(‘gameOver’, handlerFunc)

Directives DEMO BREAKDOWN 3:

ActiveTab

Directives DEMO BREAKDOWN 4:

ClickDetect

And if we have time…

`$scope` vs. `scope`$scope is assignable, but should be reserved for angular functions to pass into a controller, other context.

$scope is a shorthand, by which we're calling the $scopeProvider, which is Dependency-Injecting the scope for us. There is a long-form that looks like AMD, which is necessary when minifying, so identifiers don't get munged.

scope is just our own, customizable reference for directive’s local scope.

Link & CompileAngular’s process for assembling a page divides the work into multiple phases: compile & link (pre- & post-)

Directives have a function for each step

Think of link & compile like events, & your functions firing as handlers

We usually only need the link function.

Link vs. CompileCompile: “deals with transforming the template DOM. Since most directives do not do template transformation, it is not used often. Examples that require compile are directives that transform template DOM, such as ngRepeat, or load the contents asynchronously, such as ngView.” ie., it grabs HTML assets and morphs them if necessary. Rarely needed by users. Link: “responsible for registering DOM listeners as well as updating the DOM. It is executed after the template has been cloned.” ie., where everything else goes.

Using a Config Object (compile version)

If we need to use a compile function, that becomes the relevant property on the config object, and we return the link function from inside it.

If we provide a value for the `compile:` property, any value provided for `link:` will be ignored.

A compile function *must* return a link function.

Using a Config Object (compile version example)

.directive('sampleDirective', function(){ return { compile: function(element, attrs) { ... do compile stuff ... return function Link(scope, element, attrs) {... do link stuff ...}) }, restrict: ‘E’, template: <div>Hello, World!</div> }})

And just to add more complexity to that

structure...

Subdividing the Link (config object example)

.directive('sampleDirective', function(){ return { compile: function(element, attrs) { ... do compile stuff ... return {

pre: function(scope, element, attrs) {... do pre-link stuff ...}, post: function(scope, element, attrs) {... do post-link stuff ...}

}}}})

The link event actually consists of two sub-events: pre-link and post-link, which you can target:

Pre- vs. Post- LinkPRE-LINK: “Executed before the child elements are linked. Not safe to do DOM transformation since the compiler linking function will fail to locate the correct elements for linking.”

POST-LINK: “Executed after the child elements are linked. It is safe to do DOM transformation in the post-linking function."

But: don’t worry about these for now. Just be aware of their existence, in case you see them.

Back to challenging but useful stuff...

Directive Config Objects can provide an optional controller.

At first, you think: why?

One option: alternative to routing

Routes have controllers

Sometimes, you don’t want routes

Often Overlooked: Directive Controllers

Often Overlooked: Directive Controllers

With its own controller, a directive is a full, standalone interface component, with its own data context, which can be built or torn-down on demand.

The controller inherits, normally, from the rest of the $scope tree.

Isolate ScopeWe have the option, in directives, of using either:

the local $scope (from our own controller, possibly)a new, per-instance, ‘isolate scope’

Isolate scopes still have a parent $scope, but they’re *encapsulated*: or, detached from the inheritance chain.This is especially useful with repeats, so variables can be fully local to the instance

Creating Isolate ScopeCreating isolate scope is as simple as an object literal assigned to the `scope:` property on the config object:

.directive('sampleDirective', function(){ return { link: function(scope, element, attrs) { element.bind("mouseenter", function(){ ... do stuff after mouseenter ... } },

restrict: ‘E’, scope: {name: “Bob”,

hobby: “@”}}})

Cool! But what’s that ‘@’ doing there?

Isolate Scope Data-BindingAngular provides us with ways to bind the value of properties in isolate scope to attributes on the element, using special operators:

.directive('sampleDirective', function(){ return { link: function(scope, element, attrs) {}, restrict: ‘E’, scope: {name: “Bob”,

hobby: “@”} //alt. form:{hobby: ‘@hobby’}

}})

<sample-directive hobby=”scuba-diving”>

Data-Binding OperatorsBy default, an operator alone will be assumed to refer to a same-named attrAlternately, use form ‘@hobby’ to specifyOptions:

‘@’- binds the local scope property to primitive value of the DOM attribute. Result is always a string. (Attributes are strings.)‘=’- binds the local scope property to a parent scope property having same name as the value of the DOM attribute.‘&’- binds the local scope property to the output of an expression defined in the DOM attribute. It’s like a function-wrapper.

Isolate Scope Data-BindingThe special operators make it seem more exotic than it really is. For instance: …is basically the same as doing this in your controller: The difference is all in the fact that isolate scope is disconnected from the $scope tree, overrides local controller $scope. Plus flexible eval()…

scope.hobby = attrs.hobby;

scope: {hobby: “@”}

Final ThoughtsYour directives can have directives. (In them and on them.) Truly, it can be directives all the way down…

Thank You! !

about.me/XML