# Angular Custom Directives **Warning: This content is considered archived as .directive is no longer used - this changed between versions Angular 1.4 and 1.5. There is a somewhat updated version of the lab described here that can be found on** [**GitHub**](https://github.com/brandiw/cards-against-assembly)**. Both this project and this page are on our list to be refactored for Angular 1.5+.** ## Objectives * Describe the different types of custom directives available * Create a custom directive * Explain why custom directives are valuable ## Modularity with Custom Directives As you've seen by now, a huge amount of the code you work with in Angular are directives. Angular was designed to be an extension of HTML - a way to have custom-defined interactive tags of your own making. While we've been getting good at using the directives that come with Angular, it's time to start seeing what we can do if we start making own own. One of the most obvious *uses* of this is when you've got repetitive code to render some information or data. If you're using a bunch of tags all over the place, it's a DRY principle – you might forget a tag or decide to change something and have to change it in a million places. By extracting it to a custom directive, we can reference that directive whenever we need to use it and not worry about repeating the code to render it. ### Real World Example As an example, we're going to mess around with duplicating something that's becoming a common pattern in interface design – the concept of a card. Applications like Twitter, Pinterest, Facebook, and a lot more are moving towards this design pattern. ![Twitter](https://cloud.githubusercontent.com/assets/25366/9665317/4f8a5e56-5224-11e5-9b9c-fe62d8a6cdf4.png) Everyone's favorite CSS framework, Bootstrap, is even on board, where in [version 4+ you're able to create a card](http://v4-alpha.getbootstrap.com/components/card/) with just some CSS classes: ![Bootstrap](https://cloud.githubusercontent.com/assets/25366/9665376/c2bcac6c-5224-11e5-8e4c-807a19a4432a.png) Let's see if we can make something similar, wrapped up in our own custom HTML element. ## Cards Against Assembly #### Starter Code Take five minutes and inspect our starter code. You'll see a pretty normal Angular app, and since we're repeating using those cards, and there's a few consistent tags we're repeating every time we render a card, we're going to experiment with making those cards a custom-defined directive. ![Cards Against Assembly](https://cloud.githubusercontent.com/assets/25366/9666972/05a2f348-522e-11e5-8f6c-7c503032eff4.png) ## Building a Simple Directive Using our starter code, our goal is to take: ```markup

{{card.question}}

Cards Against Assembly
``` and end up with a reusable `` component, maybe something like: ```markup ``` ### Let's be organized! Rather than just throw this wherever, let's make a file dedicated to this directive. ``` touch js/cardView.js ``` ### Directives are as easy as... Just like controllers, factories, anything else we've made in angular, we're going to use a function to add another component. In this case, we'll make a `cardView` module and add a `directive` to it. That directive will have a function that returns everything related to the directive. ```javascript angular.module('cardView', []) .directive('card', function() { return { //stuff here } }); ``` An important thing to point out: The first argument of `directive` is the name of the directive and how you'll use it in your HTML; and remember, Angular converts `camelCase` to `snake-case` for us, so if you want to use `` in your HTML, name your directive `.directive('secretGarden', ...)`. Remember, in the official Angular docs it's called `ngClass` or `ngRepeat`, but in your HTML you use `ng-class` and `ng-repeat`. ## Directive Options There's a few interesting options when making your own directives. We'll go through them all, quickly, and you can play with them on your own in a bit. 1. `restrict` 2. `replace` 3. `template/templateUrl` 4. `scope` #### 1. `restrict` While the name isn't obvious, the `restrict` option lets us decide what *kind* of directive we want to make. It looks like this: ```javascript restrict: 'AEC' ``` * `E` is element. An HTML element, like `` * `A` is attribute. Like `
` * `C` is class. Like `
` You can choose to have just one, all of the above, or any combination you like. You should steer towards elements & attributes as much as possible, though – classes can get messy with other CSS classes. For ours, let's play with just an element. ```javascript angular.module('cardView', []) .directive('card', function() { return { restrict: 'E' } }); ``` #### 2. `replace` Replace is pretty straightforward. Should this directive replace the HTML? Do you want it to get rid of what's in the template & swap it out with the template we're going to make? Or add to it, and not remove the original. For example, replacing would mean: ```markup
``` Would actually render as: ```markup

{{question}}

Cards Against Assembly
``` See, replaced. Let's say we like that for our example: ```javascript angular.module('cardView', []) .directive('card', function() { return { restrict: 'E', replace: true } }); ``` #### 3. `template/templateUrl` This is where our partial view comes in. Now, if it's a pretty tiny, self-contained directive, you can use `template: "Some javascript " + string + " concatenation";` But that easily starts getting ugly, so it's often better (even for small directives like this) to make a quick little partial HTML file and reference it with `templateUrl` instead. Let's extract our existing card tags, and throw them in a partial. Cut out: ```markup

{{card.question}}

Cards Against Assembly
``` Quickly `touch cardView.html` or some similarly obvious-named partial, and paste it back in. In `cards/cardView.html`: ```markup

{{card.question}}

Cards Against Assembly
``` In `js/cardView.js`, we can add our option: ```javascript angular.module('cardView', []) .directive('card', function() { return { restrict: 'E', replace: true, templateUrl: 'cardView.html' } }); ``` And lastly, in our `index.html`, let's finally use our custom directive. ```markup
``` Before testing out the directive, make sure that `index.html` has the script tag for the directive, and the directive module is injected into the app. Also, remember to run this using a **HTTP server** In `app.js`: ```javascript angular.module('CardsAgainstAssembly', ['CardCtrls', 'cardView']); ``` TRY IT! So awesome! We've now got this much more readable `index.html`, with a *very* semantic HTML tag describing exactly what we want rendered. ![Cards Against Assembly](https://cloud.githubusercontent.com/assets/25366/9666972/05a2f348-522e-11e5-8f6c-7c503032eff4.png) This is awesome. This is a great, reusable component. Except for *one* thing. #### 4. `scope` If you notice, our template uses `{{card.question}}` inside it. But what if we wanted to render a card somewhere outside of that `ng-repeat`, where `card in cards` isn't a thing. What if we want to render a one-off card, reusing our new directive elsewhere? Just like controllers, we want to define what our scope is. We want to be able to say "Render a card, with these details, in whatever context I need to render it in." A card shouldn't rely on a controller's data to know what information to render inside it. The controller should pass that data to our directive, so it's freestanding and not relying on anyone but itself. That's where `scope` comes in, and this lets us decide what attributes our element should have! For example, in our card example, maybe we want to render a card with just a string somewhere outside of this controller. We want to make our own card with our own hardcoded text. Try this. In your `index.html`, adjust our `` element to say: ```markup ``` In context, you'll see that the `ng-repeat` is giving us the variable `card`, and we're actually just rendering that out as a string. But we've decided we want to have an attribute called `question` to pass data through. We made that up, it's appropriate to our example, but it can be anything. There are only two other pieces we need to make this reality. In our `cardView.html` partial, let's adjust to: ```markup

{{question}}

Cards Against Assembly
``` No longer reliant on a variable named `card`, it's now just reliant on an element having the attribute of `question`. And finally, in `js/cardView.js`: ```javascript angular.module('cardView', []) .directive('card', function() { return { restrict: 'E', replace: true, templateUrl: 'cardView.html', scope: { question: '@' } } }); ``` In `scope`, we just define an object. The key is whatever want the attribute on the element to be named. So if we want ``, then we'd need a key named `bagel` in our scope object. #### The Different Types of Scope for a Directive The *value* is one of 3 options. ```javascript scope: { myRecipient: '=', // Bind the ngModel to the object given onSend: '&', // Pass a reference to the method fromName: '@' // Store the value associated by fromName } ``` The corresponding options would look like: ```markup
``` The `=` is a mechanism for binding data that might change; the `&` is for passing a reference to a function you might want to call; and the `@` is simply storing a string & passing it through to the template. #### Since we've decided to use `@`/strings, let's try it! Our last test is to see if we can make a card using just a hardcoded string. Then we'll know our card is really reusable. Somewhere *outside* the context of the controller, let's say just above the footer in our `index.html`, throw a handmade card in: ```markup