intro to angular.js directives

Angular Directives

@ NationJS, 2013

by: Christian Lilleyabout.me/xml @xmlilley

Friday, October 4, 13

What are Directives?


Angular, Ember, BackBone: Google Trends


What Are They, Really?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.


What Are They, Really?The only other Angular construct that really touches the DOM is:

Angular Expressions (text only).

Filters

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


What AREN’T they?Directives.

Are.

Not.

Where.

Your.

JQuery.

Goes!

Please,

God:

No.


I

BUT...Friday, October 4, 13

I

Moar

“The Superheroic

MVW framework.”


And 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>


Why NOT Declarative?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 religion.



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>



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

3.Keep it Local



No...


Yes: ‘Local’Sticks to a self-contained, modular scope, which understands its context.

Uses messages, models to affect things elsewhere.

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

But the challenge is this:


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 sem, egestas nec vulputate vel, pretium sit amet mi. Fusce ut nisl id risus facilisis euismod. Curabitur et elementum purus. Duis tincidunt fringilla eleifend. Morbi id lorem eu ante adipiscing feugiat. Sed congue erat in enim eleifend dignissim at in nisl. Donec tortor mauris, mollis vel pretium vitae, lacinia nec sapien. Donec erat neque, ullamcorper tincidunt iaculis sit amet, pharetra bibendum ipsum. Nunc mattis risus ac ante consequat nec pulvinar neque molestie. Etiam interdum nunc at metus lacinia non varius erat dignissim. Integer elementum, felis id facilisis vulputate, ipsum tellus venenatis dui, at blandit nibh massa in dolor. Cras a ultricies sapien. Vivamus adipiscing feugiat pharetra.

$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 The 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()


http://api.jquery.com/addClass/

http://api.jquery.com/addClass/

http://api.jquery.com/after/

http://api.jquery.com/after/

http://api.jquery.com/append/

http://api.jquery.com/append/

http://api.jquery.com/attr/

http://api.jquery.com/attr/

http://api.jquery.com/on/


http://api.jquery.com/children/

http://api.jquery.com/children/

http://api.jquery.com/clone/

http://api.jquery.com/clone/

http://api.jquery.com/contents/

http://api.jquery.com/contents/

http://api.jquery.com/css/

http://api.jquery.com/css/

http://api.jquery.com/data/

http://api.jquery.com/data/

http://api.jquery.com/eq/

http://api.jquery.com/eq/

http://api.jquery.com/find/

http://api.jquery.com/find/

http://api.jquery.com/hasClass/

http://api.jquery.com/hasClass/

http://api.jquery.com/html/

http://api.jquery.com/html/

http://api.jquery.com/next/

http://api.jquery.com/next/



http://api.jquery.com/off/


http://api.jquery.com/parent/

http://api.jquery.com/parent/

http://api.jquery.com/prepend/

http://api.jquery.com/prepend/

http://api.jquery.com/prop/

http://api.jquery.com/prop/

http://api.jquery.com/ready/

http://api.jquery.com/ready/

http://api.jquery.com/remove/

http://api.jquery.com/remove/

http://api.jquery.com/removeAttr/

http://api.jquery.com/removeAttr/

http://api.jquery.com/removeClass/

http://api.jquery.com/removeClass/

http://api.jquery.com/removeData/

http://api.jquery.com/removeData/

http://api.jquery.com/replaceWith/

http://api.jquery.com/replaceWith/

http://api.jquery.com/text/

http://api.jquery.com/text/

http://api.jquery.com/toggleClass/

http://api.jquery.com/toggleClass/

http://api.jquery.com/triggerHandler/

http://api.jquery.com/triggerHandler/



http://api.jquery.com/val/

http://api.jquery.com/val/

http://api.jquery.com/wrap/

http://api.jquery.com/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 ... } },


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


ACK! THPPPT!!

.bind() is ancient!

Where’s .live() ?!?

.on() ?!?Friday, October 4, 13

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’})


DEMO BREAKDOWN 1


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 ... } },



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...


DEMO BREAKDOWN 2


So, about that:Model-Driven & LocalDirective Design...


Specifically, theModel-Driven

part...


Why Model-Driven?

After all, the imperative approach works fine...

...if you’re omniscient and precognitive.

... and you really, really like refactoring.


How Can Directives React to Models?

With $watch!


DEMO BREAKDOWN 3:CLOCK

haha! Get it? We’re going to usea clock to demo $watch...


Keeping Directive Design Local


How Can Directives React to Stuff that

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

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

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


DEMO BREAKDOWN 4:ActiveTab


Often Overlooked:Controllers

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: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.


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

the local $scope (from our 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() {}, restrict: ‘E’, scope: {name: “Bob”,

hobby: “@”} //alt. form:{pasttime: ‘@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.


Thank You!

about.me/xml


intro to angular.js directives

Technology

angular directives

declarative directives

settings angular

angular construct

angular isnt

factory function

directive names angular

problem declarative