This is a follow-up article to our previous one, where we explored how to create a service that would allow us to seamlessly use the browser’s localstorage, and provide a way to subscribe to changes reactively.

In this article, we shall build a simple app to explore how the reactive storage service can be used to create flexible data flows.

Create project:

Let’s begin by creating an Angular project:

ng generate new reactive-storage-service-demo

We should now have a basic project skeleton. Before we start writing code however, we will be installing Bootstrap and font-awesome to minimize the amount of work needed to make our demo look good :)

Installation:

Adding bootstrap:

npm i bootstrap --save

Adding fontawesome:

npm i font-awesome --save

Once the installation is complete, using bootstrap and font-awesome in angular is quite simple. We need to:

1. Import bootstrap and fontawesome in the style.scss file
2. Nothing. We can now directly use it on our components’ templates.

@import "~bootstrap/scss/bootstrap.scss";

@import "~font-awesome/css/font-awesome.css";

We have now installed the prerequisite libraries to deal with the UI aspect of things. We will now be creating the main part of this demo app, which is the storage service. As mentioned before, this article is a follow up to a previous one where we explain the process behind the creation of our storage service. You can find it [HERE]. Please follow along, and come back here once you have the service :)

After adding the reactive storage service, let’s see how we are going to implement it.

We will start by generating 4 components:

ng g c components/home
ng g c components/form
ng g c components/list
ng g c components/total

This will create the following files.

home.component.ts

import { Component, OnInit } from '@angular/core';

@Component({
 selector: 'app-home',
 templateUrl: './home.component.html',
 styleUrls: ['./home.component.scss']
})

export class HomeComponent implements OnInit {

   constructor() {}

   ngOnInit(): void {}

}

form.component.ts

import { Component, OnInit } from '@angular/core';

@Component({
 selector: 'app-form',
 templateUrl: './form.component.html',
 styleUrls: ['./form.component.scss']
})

export class FormComponent implements OnInit {

   constructor() {}

   ngOnInit(): void {}

}

list.component.ts

import { Component, OnInit } from '@angular/core';

@Component({
 selector: 'app-list',
 templateUrl: './list.component.html',
 styleUrls: ['./list.component.scss']
})

export class ListComponent implements OnInit {

   constructor() {}

   ngOnInit(): void {}

}

total.component.ts

import { Component, OnInit } from '@angular/core';

@Component({
 selector: 'app-total',
 templateUrl: './total.component.html',
 styleUrls: ['./total.component.scss']
})

export class TotalComponent implements OnInit {

   constructor() {}

   ngOnInit(): void {}

}

Now, we’ll call form and list components on our home.component.html :

home.component.html

<div class="container py-4">
   <app-form></app-form>
   <app-list></app-list>
</div>

Now let’s look at the form component first. As its name may more or less imply, here we will be creating a small form to add a product. The form we will be creating is shown in the screenshot below.

As you can see in Figure 1 above, the form is quite simple and straightforward. We have 2 inputs and a button to submit the data. We can however make the form a little more interesting by implementing a datalist for the product field. But first let’s add some code in our component’s ts.

form.component.ts

private products: any[] = [];
 public productNames:any = [];


getProducts(){
   this.products = [
     { 'Pizza' : 200 },
     { 'Rice' : 150 },
     { 'Bread' : 70 }
   ];
   this.products.map( (key) => {
     this.productNames.push.apply(this.productNames, Object.keys(key));
   });
 }

We start by creating two properties, products and productNames, as well as a method named getProducts().

Traditionally, in order to implement the datalist feature mentioned earlier, we would have to make an API call somewhere to fetch the list of products. For our demo purposes however, we will hardcode the data in this method itself & assign it to the products class property we have created above. The list will be an array of key/value pairs representing product names and prices.

Next, in order to generate the datalist for our html, we will need an array of strings containing only the product names. We achieve this by using the apply method to push one array into the other. We can then display the list of product names in our template, which will be our form.component.html

Let’s have a look at our html and see how are we going to display our productNames :

form.component.html

<div class="mb-3 row">
   <label for="productDataList" class="col-sm-3 text-end col-form-label"> Product</label>
   <div class="col-sm-8">
       <input class="form-control" list="productOptions" id="productDataList" placeholder="Type to search..." required>
       <datalist id="productOptions">
           <option *ngFor="let opt of productNames" value="{{opt}}"></option>
       </datalist>
   </div>
</div>

The interesting tags here are the input and datalist elements. A few interesting things to point out are that

• The <input> element has a list attribute that is set to “productOptions”
• The <datalist> element has an id, which is also set to “productOptions”
• The <datalist> element contains an <option> tag will be repeated for every element in our array of product names.

By setting the list attribute to the same value as the id of our datalist, we are effectively binding those two elements. We will then be displaying our productNames inside of the <datalist> , so we use an *ngFor on the productNames in our <option> tag, and add each product name to the value attribute.

What we just achieved is that our <input> is now no longer a simple text box, as values from the datalist will be used to turn it into an autocomplete enabled textbox.

“But!”, I hear you ask, “Couldn’t we have just used a <select> here and list the options in there?”, which is an excellent question. We indeed could have done that, but note that we have a different use case here. our input+datalist solution is more flexible, since now the user can enter their own value if what they want is not in the predefined list.

Alright! Next, upon selecting an existing product, we’ll want to populate its corresponding price as shown in figure 1.

In order to achieve this, we will need to rely on browser events. We will look at our html first, and then create the corresponding bindings in our component ts.

In our form.component.html , let’s add a “keyup” attribute to our product input, and calling the onChangeProduct() method, which we will be creating in our ts shortly. The method will take the event data $event as its only parameter. Basically the $event will contain the value of our product textbox.

form.component.html

<input class="form-control" (keyup)="onChangeProduct($event)" list="productOptions" id="productDataList" placeholder="Type to search..." required>
<datalist id="productOptions">
  <option *ngFor="let opt of productNames" value="{{opt}}"></option>
</datalist>

Next, let’s take a look at our ts. We first add a new public property to our class called “currentProduct”, which will contain the details that we want the form to submit. We then add the onChangeProduct() method.

form.component.ts

public currentProduct: any = {
   name: '',
   price: 0
 };
 

onChangeProduct(event: any): void{

   const value = event.target.value;
   this.products.map( prod => {
     if (Object.keys(prod)[0].includes(value)){
       this.currentProduct.price = Object.values(prod)[0];
     };
   });

 }

Within the method, we create a new variable called “value”, and assign it to our product textbox’s value through the “event” parameter using “event.target.value”.

Now, since as mentioned earlier we are not using a <select> element for the product name, and the user thus has the option to enter their own value, we cannot guarantee that the value entered in the textbox has a corresponding price. As such, we’ll need to check if the name of the product entered exists in our list, and therefore has a corresponding price. If it does, we’ll assign it to this.currentProduct.price

After updating this.currentProduct.price we now need to populate our price input in our html with its value.

Angular provides us with a few ways to change a form input’s value programmatically from our component ts file. The one we will use here is the [(ngModel)] directive.

ngModel is a directive provided by angular’s form module, and it allows us to set up either one or two way binding between our form input and a property of our component class. In order to use the directive however, we need to first import the required module in our app.module.ts file

Please note that since you have modified the app.module.ts file, you will need to serve your application once again for changes to our module file to take effect.

Once this is done, we can go back to our html. We will be using bootstrap classes to make the UI more interesting. Here we will be using an input group to be able to add a $ sign in front of the price input.

In order to populate the updated price in the input, we are binding it to our class property currentProduct.price using the [(ngModel)] directive on our input tag, so that each time we are changing the product, it will update to the corresponding price.

form.component.html

<div class="mb-3 row">
   <label for="inputPrice" class="col-sm-3 text-end col-form-label">Price</label>
   <div class="col-sm-8">
       <div class="input-group mb-3">
           <span class="input-group-text" id="basic-price"><i class="fa fa-dollar" aria-hidden="true"></i></span>
           <input type="text" [(ngModel)]="currentProduct.price" class="form-control" id="inputPrice" placeholder="Price" aria-label="Price" aria-describedby="basic-price">
       </div>
   </div>
</div>

Now we need to do the same for our product input, binding it to currentProduct.name so that the product name is also synced with our currentProduct property.

<div class="mb-3 row">
    <label for="productDataList" class="col-sm-3 text-end col-form-label">Product</label>
    <div class="col-sm-8">
        <input class="form-control" (keyup)="onChangeProduct($event)" [(ngModel)]="currentProduct.name" list="productOptions" id="productDataList" placeholder="Type to search..." required>
        <datalist id="productOptions">
            <option *ngFor="let opt of productNames" value="{{opt}}"></option>
        </datalist>
    </div>
</div>

We’re almost done with the form. Last but not least, we now need to save the form data to the storage.

First, let’s add a click event to our button in our html. We will bind the click event to an addProduct() method, that we will create shortly on our form.component.ts.

form.component.html

<button type="button" class="btn btn-success btn-sm" (click)="addProduct()">
    <i class="fa fa-paper-plane me-1" aria-hidden="true"></i>
      Save
</button>

We will now create our addProduct() method in our ts file, which is going to add the product to our storage.

We begin by creating a new variable called storageProductList. This will be an array that we will use as a proxy to the data that is in our storage.

After that, we’ll get all the products from storage and assign it them our storageProductList. If there is no value in the storage we’ll just set it to an empty array.

We can then push our current product (that has been synced into this.currentProduct with the two ngModel directives in our html) into the storageProductList and then set it back to our storage with this.storage.set(‘products’, this.storageProductList);

form.component.ts

public storageProductList: any = []; 

addProduct(): void{
     this.storageProductList = this.storage.get('products');
     if (!this.storageProductList) {
       this.storageProductList = [];
     }
     this.storageProductList.push({...this.currentProduct});
     this.storage.set('products', this.storageProductList);
   }

 }

form.components.html

form.components.ts

Now that we are done with the form, we will be looking at the list. First, let’s check the list UI. We want to build something like the following:

As you can see in Figure 2 above, it is a list of all the products from the localstorage. In the table we have 3 columns: the product name, the product price (in dollars) & a column for the delete button for each product. Let’s add some code in our component’s ts file;

We’ll first declare the productList$ & inject the storage service

list.component.ts

productList$ = this.storage.watch('products');

 constructor(
   public storage: StorageService
 ) { }

It is worth noting that since we know the watch method of our storage service will be returning an observable, we can create a stream directly simply by assigning it to our productList$ property. This will enable us to access the data directly in our template by using an async pipe.

Next, we’ll display the product in a table by using *ngFor on the productList$ | async and displaying the name & price. As mentioned above, the async pipe is used to resolve the observable stream. In order to format the price in a suitable format we’ll add a currency pipe when rendering the price ( item.price | currency )

list.component.html

<table class="table table-striped table-hover">
   <thead>
     <tr>
       <th scope="col">Name</th>
       <th scope="col" class="col-2 text-center">Price (<i class="fa fa-dollar" aria-hidden="true"></i>)</th>
       <th scope="col" class="text-end pe-5 col-2">Action</th>
     </tr>
   </thead>
   <tbody>
     <tr *ngFor="let item of productList$ | async">
       <td>{{item?.name}}</td>
       <td class="text-center">{{item?.price | currency}}</td>
       <td class="text-end pe-5">
           <button class="btn btn-danger btn-sm" (click)="removeStoreProduct(item.name)">
               <i class="fa fa-trash" aria-hidden="true"></i>
           </button>
       </td>
     </tr>
   </tbody>
 </table>

Then let’s check on how we’ll remove a product from the list. Notice that in the markup above, we have a click event in our button, binding to a removeStoreProduct() method, passing the item name as an argument.

We will therefore create our removeStoreProduct() method in our ts file, in which we are going to remove the product to our storage. By passing the product name as a parameter, we’ll be able to filter on our list directly. But first, similarly to when we were adding a product, let’s get the products from our storage with this.storage.get(‘products’) , and assign it to a list variable.

Next we’ll filter on the list and remove the product with the same name as the one that we have passed as parameter

list = list.filter( (x:any) => x.name != name );

and then set the list back to our storage

this.storage.set(‘products’, list);

and tada… it’s done :)

list.component.ts

removeStoreProduct(name: string): void{
   let list = this.storage.get('products');
   if (!list) {
     list = [];
   }
   list = list.filter( (x: any) => x.name != name);
   this.storage.set('products', list);
 }

And we are functionally done with the list :) but before moving on, let’s add the <app-total> selector at the bottom of our list in order to call the total component here.

list.component.html

list.component.ts

Alright. At this point our form and list are done. You can test that adding a product in the form indeed populates the list, and removing a product also works, without us having to manually communicate updates between the components.

Now let’s look at the total component. Ultimately we want to have something like the following UI:

As you can see in Figure 2 above, we are adding a total and also calculating a discount of 5% and adding a 15% of VAT to the subtotal. Let’s add some code in our total component’s ts.

We’ll first of all declare variable displayProductData as an object, which will contain all the information we want to display (i.e our subtotal, discount, vat and the total), and setting all their initial values to 0.

total.component.ts

displayProductData: any = {
   subtotal: 0,
   discount: 0,
   vat: 0,
   total: 0
 };

Next, once again, we’ll inject storage service in the constructor.

total.component.ts

constructor(
   public storage: StorageService
 ) { }

We will be doing all the calculations in the ngOnInit() method, we could also create a method for the calculation and call it on our ngOnInit().

Let’s start by subscribing to the watch() method for our products on our storageService. This will again provide us with an observable pipeline that will allow us to subscribe to updates in the product list in our localstorage. Initially however, since there will be nothing in our storage the first time we run the application, we need to check if our res is not null before proceeding.

We can then create a prices array from the product list by aggregating the results in our subscribe, as we will only need the prices here.

We will begin by using the map method to transform our array of objects into an array of prices, that we will use to calculate our subtotal.

So basically if there’s only 1 item in our prices array, we will just set the subtotal to the first element in the prices ( thus prices[0] ). Otherwise, we will use the reduce function (i.e prices.reduce()) to obtain the sum of all prices in the array.

Next for the 5% discount, we’ll just multiply 0.05 by the subtotal.

0.05 * this.displayProductData.subtotal

And assign it to this.displayProductData.discount

Regarding the VAT (15%), same principle, we’ll be multiplying 0.15 * this.displayProductData.subtotal and assign it to this.displayProductData.vat

Finally, for the total, we’ll do subtotal minus discount plus VAT, so

this.displayProductData.total = this.displayProductData.subtotal — this.displayProductData.discount + this.displayProductData.vat;

total.component.ts

ngOnInit(): void {
   this.storage.watch('products')?.subscribe( res => {     if (!res) return;
     const prices = res.map( (x: any) => x.price);
     this.displayProductData.subtotal = (prices.length > 1) ?
     prices.reduce( (a:number, b:number) => a+b, 0 ): prices[0];

     this.displayProductData.discount = 0.05 * this.displayProductData.subtotal;
     this.displayProductData.vat = 0.15 * this.displayProductData.subtotal;
     this.displayProductData.total = this.displayProductData.subtotal -           this.displayProductData.discount + this.displayProductData.vat;

   });
 }

All good! So now everytime we get an update from the storage service, our component will recalculate all the values. We can now go ahead and use it in our html :)

Speaking of our html, we’ll be displaying the subtotal, discount, VAT and total in dl, dt & dd. We’ve added dt on subtotal and total to make it bold and also increased the size for the total by adding an fs-5 class. And also add a pipe currency on each item.

total.component.html

<dl class="text-end pe-5">
   <dt>{{displayProductData.subtotal | currency}}</dt>
   <dd>{{displayProductData.discount | currency}}</dd>
   <dd>{{displayProductData.vat | currency}}</dd>
   <dt class="fs-5">{{displayProductData.total | currency}}</dt>
</dl>

total.component.html

total.component.ts

And we’re done! Now we can add products using the form, they’ll automatically update the list and total component. Removing a product from the list will also update the total as well. All this works across the 3 components with our localstorage acting as a source of truth. What is even better is that since we are using localstorage, this state is also persisted across page loads.

This concludes our short showcase of how to use the reactive storage service. Of course this is just a simple use case of what can be done using this pattern, but we are already excited about all the possibilities this approach enables.

Any thoughts, questions or improvement ideas? We would be delighted to hear from you :)

You can find a live demo: https://reactive-storage-service-demo.herokuapp.com/

And the code on Github: https://github.com/Bilkiss/reactive-storage-service-demo

Keep safe and keep learning :)

As frontend developers we love beautiful UI. In the same vein, we really should strive to have clean reusable code. Modern tools and techniques provide us with many ways to achieve that. In this article, we will look at typescript decorators, and how they can help us add abstraction and reusability to our code.

We will do that by creating a custom decorator to launch a Sweetalert.

But first of all let us look at what decorators are.

When I was first introduced to decorators, I wondered why we needed them at all. I mean sure, Angular uses that @Whatever symbols everywhere but how did they actually work? Ultimately they looked like black boxes. And surely, one can build apps in TS / Angular without understanding them. But once we dig a little deeper we can understand what they are, as well as the benefits of using them.

What are decorators?

At its core, a decorator is just a JavaScript function. Ok i know this sounds like a joke but really! A decorator is just a function that allows us to “extend” our code to do more. Yes it’s very abstract for now but we’ll get to clarify that soon.

Let’s look at the different types of decorators available in typescript.

There are four main types:

• Class decorators, which are used to add functionality to a class e.g. @Component and @NgModule
• Property decorators for adding functionality to properties inside classes, e.g. @Input and @Output
• Method decorators for methods inside classes, e.g. @HostListener
• Parameter decorators for parameters inside class constructors, e.g. @Inject

Each decorator has a unique role. For examples of the different decorator types and their application in angular, please check Decorators used in Angular.

Those are the basics you should know before we can jump into the fun part, actual code :) As mentioned earlier, we will be creating a method decorator that will show a sweetalert confirmation box before a method is executed.

OK let’s start!

As mentioned earlier, decorators are actually just functions, it’s as simple as that, and are called with whatever they are decorating. A method decorator will be called before the method it’s decorating, and a class decorator will be called before the class to be decorated.

I am assuming you already have an angular project, but if not you can create one with

ng new

Let’s quickly make a decorator that we can use in a class to demonstrate this a little further. The decorator we’ll be building is a confirmable decorator, which will ask for confirmation before executing a method. We will be using SweetAlert 2 as our popup plugin.

Installation:

To install sweetalert we need to run the following command in the terminal

npm install --save sweetalert2

Once the installation is complete, using sweetalert in angular is quite simple. We need to:

1. Import the library in our component
2. Call Swal.fire(); to show the popup.

For example consider the code sample below:

(This code sample is just for illustrative purposes, you will not need this component in the project).

In the above example, when the component is initiated, an alert box will appear

Now that we have looked at the basic usage of sweetalert, let’s write some code. First, we will create a component, which will be our starting point for this adventure. As usual we will use the cli.

ng g c item

This will create the following file.

item.component.ts

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-item',
  templateUrl: ‘./item.component.html',
  styleUrls: ['./item.component.scss']
})

export class ItemComponent implements OnInit {

constructor() {}

ngOnInit(): void {}

}

Nothing too fancy for now. We will be adding a delete method to this component class, which will simply log a message to the browser console.

item.component.ts

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-item',
  templateUrl: ‘./item.component.html',
  styleUrls: ['./item.component.scss']
})

export class ItemComponent implements OnInit {

 constructor() {}

 ngOnInit(): void {}

 deleteItem(): void {
  console.log(“An item was deleted”);
 }

}

And in the component’s markup, we will add a button to trigger the newly created method.

item.component.html

<button (click)=”deleteItem()”>Delete item</button>

If we load the component and click the button, the console will indeed log the message. So far so good, but what if we wanted to ask the user to confirm this action rather than directly running the method?

One option would be to call sweetalert within the deleteItem method itself, and this would work ok, but what if we wanted this to be a reusable logic, so that it wouldn’t need to be copy/pasted every time we have a functionality requiring a user confirmation? I know you were waiting for it, this is where our decorator will come in!

So for the next step, we will create a folder named “decorators” in our app directory, and within it add a new blank typescript file named confirmable.decorator.ts.

The first thing we will do in that file is to import sweetalert.

confirmable.decorator.ts

import Swal from 'sweetalert2';

Next, remember how we were saying that decorators were simple TS functions? Those functions’ signatures look like the following for method decorators:

function confirmable(target: Object, propertyKey: string, descriptor: PropertyDescriptor)

Where “target” represents the class containing the method we’re decorating, “propertyKey” represents the method name, and “descriptor” will contain the method implementation. Within the decorator function we are able to do things before / after the method executes, or skip execution altogether based on arbitrary conditions. For example

function decorator(target: Object, propertyKey: string, descriptor: PropertyDescriptor){

 // we first cache the original method implementation
 const originalMethod = descriptor.value;

 // then we overwrite it with a new implementation,
 // ...args represent the original arguments

 descriptor.value = function (...args) {

  // do custom logic before executing the original method
  // execute original method with the original arguments
  const result = originalMethod.apply(this, args);

   // execute custom logic after executing the original method
   return result;
  }

 };

 return descriptor;

};

As we can see in the method above, using decorators we can inject logic to our decorated method. This decorator would then be used by importing the function in our component.ts, and prepending it to our method definition as follows

@decorator
myDecoratedMethod(){.....}

Makes sense? Now let’s try it for real on our confirmable decorator :)

confirmable.decorator.ts

import Swal, {SweetAlertOptions} from 'sweetalert2';

export function Confirmable (target: Object, propertyKey: string, descriptor: PropertyDescriptor) {

 // Again, cache the original method for later use
 const originalMethod = descriptor.value;

 // the configuration object for sweetalert
 const config: SweetAlertOptions = {
  title: 'Are you sure?',
  html: 'Do you want to perform this action?',
  showDenyButton: true,
  confirmButtonText: 'Yes',
  denyButtonText: 'No',
  icon: 'question'
 };

 // we write a new implementation for the method
 descriptor.value = async function (...args) {

   const res = await Swal.fire(config);  
   // fire sweetalert with the config object

   if (res.isConfirmed){ // if user clicked yes,

   // we run the original method with the original arguments
   const result = originalMethod.apply(this, args);
  
   // and return the result
   return result;
  }
 };

 return descriptor;
 };

}

So now, any method decorated with our decorator will ask for a confirmation, and will only be executed if the user clicks “Yes”. we will now implement it in our item component.

item.component.ts

import { Component, OnInit } from '@angular/core';
import { Confirmable } from '../decorators/confirmable.decorator';

@Component({
 selector: 'app-item',
 templateUrl: ‘./item.component.html',
 styleUrls: ['./item.component.scss']
})

export class ItemComponent implements OnInit {

 constructor() {}

 ngOnInit(): void {}

 @Confirmable
 deleteItem(): void {
   //Code to delete your item
 }

}

item.component.html

<button (click)=”deleteItem()”>Delete item</button>

And here we go. Now when clicking the button, our decorator shall trigger asking for a confirmation, and only if the user clicks “yes” will our deleteItem method executed.

Passing data to the decorator

Our previous solution definitely works, but there is in my opinion a small flaw in our implementation which makes it a bit inflexible: Using this decorator, the confirmation title and message are hardcoded in the decorator logic, and as such we will have the same message for every confirmation box throughout our application. While this may be acceptable in some use cases, this is definitely not always the case!

The solution to this is to use decorator factories. Instead of having our decorator ts file export our decorator function directly, we will export a callable function, which will return our decorator function. The subtle difference here is that our callable factory function will be able to accept parameters, which can be used to further customize our decorator’s behavior.

This sounds a little abstract, so again let’s look at code :)

To use this new version of our decorator, we must now update our component code to reflect the fact that “Confirmable” is now a callable function returning our decorator, rather than the decorator itself.

Now we can pass the different keys from the @Confirmable() call itself. A few things to note here are that:

• The options parameter is optional. As such @Confirmable() would work just as well.
• Since we set the type of options to “SweetAlertOptions”, typescript and your editor will kick in and you should get autocompletion for the option object’s available properties :)

Again, running the code and clicking the delete button will show our sweetalert confirmation box :)

Now, anytime we’ll need to get user confirmation for an action, we can just import our confirmable decorator, and apply it on the methods we need the confirmation on.

This was just an example of what can be achieved using decorators. The goal is to factor out reusable functionalities that can then just be imported to be used.

Keep safe and keep learning :)

Building custom typescript decorators for angular was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

Angular offers us a few class decorators. These are the top-level decorators that we use to express intent for classes. They allow us to tell Angular that a particular class is a component, or module, for example. And the decorator allows us to define this intent without having to actually put any code inside the class.

A @Component:

Are decorators that mark a class as an Angular component and provide configuration metadata that determines how the component should be processed, instantiated, and used at runtime.

and @NgModule:

Are decorator that mark a class as an NgModule and supplies configuration metadata.

Here are the decorators example with classes:

Notice how both classes by themselves are effectively the same. No code is needed within the class to tell Angular that it is a component or a module. All we need to do is decorate it, and Angular will do the rest.

Property Decorators

These are probably the second most common decorators that you’ll come across. They allow us to decorate specific properties within our classes — an extremely powerful mechanism.

Let’s take a look at @Input():

Are decorators that mark a class field as an input property and supplies configuration metadata. The input property is bound to a DOM property in the template. During change detection, Angular automatically updates the data property with the DOM property’s value.

Imagine that we have a property within our class that we want to be an input binding.

Without decorators, we’d have to define this property in our class anyway for TypeScript to know about it, and then somewhere else tell Angular that we’ve got a property that we want to be an input.

With decorators, we can simply put the @Input():

Are decorators that mark a class field as an output property and supplies configuration metadata. The DOM property bound to the output property is automatically updated during change detection.

They are decorators that are above the property — which Angular’s compiler will automatically create an input binding from the property name and link them.

We’d then pass the input binding via a component property binding:

The property decorator and “magic” happens within the ExampleComponent definition. Here, with the <example-component> tag there is a single property exampleProperty which is decorated, which is easy to change, maintain and track as our code base grows. You can call your <example-component> tag on any component and can use it as a template.

Method Decorators

@HostListener:

Are decorator that declares a DOM event to listen for, and provides a handler method to run when that event occurs.

Method decorators are very similar to property decorators but are used for methods instead. This let’s us decorate specific methods within our class with functionality. A good example of this is @HostListener. This allows us to tell Angular that when an event on our host happens, we want the decorated method to be called with the event.

Parameter Decorators

Parameter decorators are quite interesting. You may have come across these when injecting primitives into a constructor, where you need to manually tell Angular to inject a particular provider.

Parameter decorators allow us to decorate parameters in our class constructors.

Due to the metadata that TypeScript exposes for us we don’t actually have to do this for our providers:

constructor(@Inject(MyService) myService) {
   console.log(myService); // MyService
}

We can just allow TypeScript and Angular to do the hard work for us by specifying the provider to be injected as the parameter type:

Now that we’ve covered the types of decorators we can use, let’s dig into what they actually are doing — and why we need them.

In this 2-part series, we are looking at how to implement custom directives in Angular. As a reminder, in the first part, we looked at how to create a custom attribute directive to implement a drag & drop file upload functionality.

In this second part, we are going to look at structural directives, and how to use them to dynamically change our DOM structure.

What are directives?

As we have discussed before, there are three kinds of directives in Angular:

1. Components — directives with a template.
2. Attribute directives — change the appearance or behavior of an element, component, or another directive, and
3. Structural directives — change the DOM layout by adding and removing DOM elements.

Components are the most common of the three directives and are one of the core building blocks in the Angular framework to build applications. They are basically the same as an attribute directive except that their selector is actually a tag, and they have an associated template markup.

On the other hand, attribute directive, such as our previously visited FileUploadDirective, changes the appearance and/or behavior of the host DOM element according to the logic implemented.

Finally, structural directives, which we’ll be looking at today, can change our DOM structure, usually by adding, removing, or manipulating elements. As with other directives, structural directives are usually applied to a host element. The directive then does whatever it’s supposed to do with that host element and its descendants.

Structural directives are easy to recognize in html markup: the directive’s attribute name is always preceded by an asterisk (*).

<span *ngIf=”user” class=”name”>Welcome {{user.name}} !</span>

In the above example, the span is either present or absent from the dom, depending on whether the “user” property of our component class is set or not.

Structural directives are important as they let us control the DOM and how it reacts to changes in our underlying data. Now let’s see how to build our own.

How to create our structural directive

The process to create a structural directive is not very different from the one to create an attribute directive. Again, we can simply use the CLI to generate our class. For example:

ng g directive directives/myStructuralDirective

This will generate a new typescript class decorated with the @Directive decorator, which will contain our directive’s implementation logic.

So, what are we building today?

The structural directive we are building will allow us to conditionally attach or remove an element in our dom, depending on whether a logged in user has a specific role and as such the permission to see the element our directive will be attached to. Sounds hard? No worries, as usual we’re going to take it slow :)

Step 1. Generating the class file

Similarly to an attribute directive, a minimal structural directive would consist of a class annotated with the @Directive decorator, which specifies the selector that identifies our directive. This class will then implement the desired directive behavior.

So we begin by generating our directive class using the CLI

ng generate directive directives/enableForRole

This command will do three things:

1. Generate our class file at ‘src/app/directives/enable-for-role.directive.ts’,
2. Generate a corresponding test file at ‘src/app/directives/enable-for-role.directive.spec.ts’, and
3. Declare the directive class in our root AppModule.

The generated main directive class enable-for-role.directive.ts will look as follows:

import { Directive} from ‘@angular/core’;

@Directive({
  selector: ‘[appEnableForRole]’
})

export class EnableForRoleDirective {

  constructor() {}

}

Here we are importing the @Directive decorator, and using it to configure our directive class. The directive’s selector is defined by default as ‘[appEnableForRole]’, but let’s change that to ‘[enableForRole]’ for convenience and readability.

Again, similarly to attribute directives’ selectors, It’s the brackets ([]) that make it an attribute selector. Angular will locate each element in the template that has an attribute named appEnableForRole and apply the logic of this directive to that element.

As opposed to attribute directives though, when using our structural directives in our markup, we need to prefix its selector with an asterisk (*). This is how Angular can tell that this is a structural directive rather than just a regular old attribute directive. Below is an example of how we would use this particular structural directive in our markup:

<p *enableForRole=”admin”>This tag is only displayed for admin users!</p>

But let’s not get ahead of ourselves just yet. We still need to build the logic of our directive!

Step 2. Adding the necessary imports

After the @Directive decorator comes the directive’s class, called EnableForRoleDirective, which contains the (currently empty) logic for the directive. Exporting EnableForRoleDirective makes the directive accessible.

We will now edit the generated src/app/directives/enable-for-role.directive.ts file. First, we will import TemplateRef and ViewContainerRef from ‘@angular/core’, and inject them in our constructor. The resulting file shall look as follows:

import { Directive, TemplateRef, ViewContainerRef } from ‘@angular/core’;

@Directive({
 selector: ‘[enableForRole]’
})

export class EnableForRoleDirective {

constructor(
 private templateRef: TemplateRef<any>,
 private viewContainerRef: ViewContainerRef
 ) {}

}

We have added two new imports to our directive class. What do they do?

Well let’s begin with TemplateRef.

TemplateRef represents the contents of an embedded <ng-template> that can be used to instantiate embedded views. In short, it will basically contain the innerHTML of our host element. In our case, this would be the content we want to add/remove depending on the user role.

Next is the ViewContainerRef. We will be using this class to either instantiate a new embedded view based on the contents our TemplateRef described above, or clear the content if the user doesn’t have the necessary role.

So, in a very simplified summary, our TemplateRef will contain the innerHTML structure of our directive’s host element, and our ViewContainerRef will enable us to either render this content or clear it.

Sidequest 1: More about <ng-template>

In the last step, we have seen that TemplateRef will reference the contents of an <ng-template> element. But what does that mean?

Ng-template is a virtual element in angular. What thi means is that tags within a pair of <ng-template> tags will not be rendered by default. This is useful if we need to control when to include / exclude specific blocks of markup from the rendered DOM.

But wait, we aren’t using any ng-template tags in our markup, so how will this work? Well, it is all thanks to the structural directive :) Remember how we said that we would use our new directive like the following?

<p *enableForRole=”admin”>This tag is only displayed for admin users!</p>

Well, because of that asterisk, this code will be transformed by angular into the following:

<ng-template [enableForRole]=”`admin`”>
  <p>This tag is only displayed for admin users!</p>
</ng-template>

And our TemplateRef will therefore contain our <p> tag.

Step 3. Implementing the actual logic

We will now (finally) be writing the logic of our directive. So in short what we will be doing here is firstly, create a virtual property with the same name as our selector, to which we will be assigning our desired role from the html. We do this by creating a setter, which will run anytime we try to assign a value to the property, and decorating it with the @input decorator, so that it will have access to the role we are assigning from the html.

We will then get the user data from storage (presumably we will have saved it there after a sign in) and check whether the user has the role specified above. If they do, we will render the contents of the TemplateRef inside our ViewContainerRef. Else we will clear the ViewContainerRef. Here is what the completed code looks like:

Sidequest 2: Mocking our user data

In our directive, we are fetching the user object from the browser’s localStorage. Usually we will have saved it there when a user successfully logs in. For the sake of brevity in this demo however we will be directly mocking the data inside our storage.

In our browser’s developer tools console, we can inject data into the storage by using the following commands.

// Mocking an admin

localStorage.setItem(“user”, JSON.stringify({
 first_name: “Test”,
 last_name: “Lastname”,
 role: “admin”,
 email: “admin@test.io”
 }) );

And to overwrite the mocked data with a non admin user, we can run

// Mocking a normal user

localStorage.setItem(“user”, JSON.stringify({
 first_name: “Test”,
 last_name: “Lastname”,
 role: “user”,
 email: “user@test.io”
 } ));

And we now have our mock user data inside our storage.

Step 4. Apply the attribute directive

To use the new EnableForRoleDirective, We will add a paragraph (<p>) element to the template of our AppComponent and apply the directive as an attribute.

<p *enableForRole=”`admin`”>I am an Admin!</p>

Now we can run the application to see the EnableForRoleDirective in action.

ng serve

You will notice that depending on what user role is stored in our storage, The directive will insert or remove our <p> tag accordingly.

To summarize, Angular found the EnableForRole attribute on the host <p> element. It created an instance of the EnableForRoleDirective class and injected a reference to the <p> element into the directive’s constructor which will show or hide the <p> element depending on the user role.

So, in conclusion, a structural directive is not that different from an attribute directive. The main thing that differentiates the two variants is that the structural directives allow us to easily modify the dom structure by allowing us to access and manipulate the dom structure of our host elements’ DOM structure.

Also, by digging around, you may notice that the directive does not yet react to changes to the login status. We will look at how to use rxjs to make it a bit more reactive in a future article.

Angular custom directives was originally published in The Startup on Medium, where people are continuing the conversation by highlighting and responding to this story.

Forms are a very important part of any real, non trivial application requiring user input. From simple static forms to dynamic event driven reactive forms, Angular provides us with tools and modules to build powerful forms. In this short series of articles, we are going to explore the tools that the framework provides us to build, handle and maintain forms throughout your application. In this first part we shall explore Angular’s Reactive Forms module.

Reactive forms? what’s that again?

Before we take a deep dive into the code, we need to understand what the tool is, and what we are going to build with it. so, what in the heavens is a reactive form?

In Angular, the reactive forms module provides us with an explicit and immutable approach to managing the state of a form at a given point in time.

In practical terms, it means that our components’ typescript code will hold a model representing our form, the fields within it, the value of said fields as well as the validation rules and validity status of our form.

Each change to the form state will return a new state, which maintains the integrity of the model between changes. Reactive forms are built around observable streams, where form inputs and values are provided as streams of input values, which can be accessed synchronously.

Reactive forms differ from template-driven forms in a few distinct ways. For instance, Reactive forms provide more predictability with synchronous access to the data model, immutability with observable operators, and change tracking through observable streams.

Ok now with that out of the way, let’s take a look at how we will build a reactive form.

Step 1. Generating angular-forms project

So as usual, we will begin by generating a new project for our little exploration of reactive forms.

ng new angular-forms

We will enable routing and choose scss as our style language as this is what we’ll be using throughout this series, but you may do otherwise depending on your needs).

Step 2. (Optional) Installing bootstrap and font-awesome

We will be using bootstrap as well as font awesome in order to make our form’s UI look more aesthetically pleasing. This can be done by running the following command.

npm install --save bootstrap font-awesome

After the installation is done, we can import the two libraries by adding the following lines in our styles.scss file (located in the src directory of your app)

@import "~bootstrap/scss/bootstrap";
@import "~font-awesome/css/font-awesome.min.css";

Step 3. Import ‘ReactiveFormsModule’

We will now import `ReactiveFormsModule` inside our application’s file (typically app.module.ts). The module can be imported from @angular/forms as follows:

import { ReactiveFormsModule } from '@angular/forms';

After that, we’ll need to add the module in our imports array for it to be available to our components. Our app.module.ts file should look like below.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';
import { ReactiveFormsModule } from '@angular/forms';

@NgModule({

  declarations: [
    AppComponent
  ],

  imports: [
   BrowserModule, 
   AppRoutingModule, 
   ReactiveFormsModule
  ],

  providers: [],

  bootstrap: [AppComponent]

})

export class AppModule { }

We now have access to Angular’s ReactiveFormsModule from our application’s components.

Now before we continue, there are a few key concepts that we need to be familiar with, namely

• Form Controls,
• Form Groups, and
• Form Builders.

The FormControl object will represent your form inputs. each input will need to have a corresponding FormControl object in your compnent’s ts file. These objects will keep track of the input’s default value, updated value, validation rules and status.

A FormGroup will represent a group of FormControl objects. It will have similar properties and keep track of the different controls within it.

Finally, the FormBuilder class is a helper class that will help us to easily build our form’s group/control structure as well as assigning default values and validation rules.

Sounds a bit vague? No problem, let’s jump into some code :)

Step 4. Component

For this demo, we will be using a cv component, that will present us a form to input our CV’s details. So let’s create our cv component with the following command

ng g component components/cv

We should now have a new component :)

We will now add it in our app-routing.module.ts

Step 5. Form Logical Structure

In our newly created cv.component.ts we will begin by importing FormBuilder, Validators, and FormGroup from @angular/forms.

import { FormBuilder, FormGroup, Validators} from "@angular/forms";

As described above, FormBuilder is a helper class that will aid us in setting up our form model. Validators contains a set of inbuilt validators that we can use in our form, and FormGroup will help us organize our form’s structure.

Next we’ll add a property of type FormGroup to our class. this form group will represent our example form.

cvForm: FormGroup;

We can now inject the FormBuilder service class in our component’s constructor as follows

constructor(private fBuilder: FormBuilder) { }

We can now use the FormBuilder service in our cv component.

The FormBuilder service has three methods: control(), group(), and array(). These are factory methods for generating instances in your component classes including form controls, form groups, and form arrays.

Inside our component’s ngOnInit method, we will be using the group method to create our controls.

ngOnInit(): void {

  this.cvForm = this.fBuilder.group({
    email: [‘’],
    password: [‘’],
    confirm_password: [‘’],
    rating: [0],
    skill_name: [‘’]
  })

}

In the example above, we are using the FormBuilder’s group() method with an object to define the properties of our form. The value for each control name is an array containing the initial value as the first item in the array (here an empty string for every field except rating, which we are setting to “0”).

Our form will therefore have 5 inputs, namely for the email, password, password confirmation, a skill name and its rating.

We don’t have any validation rules applied yet though. Let’s fix this.

Step 6. Validation

Form validation is used to ensure that user input is complete and correct. To summarize, the steps to add validation to a form control are as follows:

1. e need to Import a validator function (custom or inbuilt) in our component.
2. We will then add the validator to the form control.
3. And finally add logic to handle the validation status.

One of the most common validation use cases is making a field required. Let’s try doing exactly that:

If you look at the code we’ve written so far, you’ll notice that, at the very beginning of our component code, we are importing Validators from “@angular/forms”. What does this do? Well, reactive forms include a set of validator functions for common use cases. These functions receive a control to validate against and return an error object or a null value based on the validation check.

In the form initialization code, we will add the `Validators.required` static method as the second element in the array for the different form controls.

this.cvForm = this.fBuilder.group({
  email: ['', Validators.required],
  password: ['', Validators.required],
  confirm_password: [''],
  rating: [0, Validators.required],
  skill_name: ['', Validators.required]
})

You will notice right away that we’re not applying the validator to the confirm_password field here. For that we shall add a custom validator to compare the passwords entered.

For simplicity’s sake, we will write the custom valdation function directly after our ngOnInit method. please note that usually in most cases you would want to externalize custom validator functions so that they can be reused.

Let’s call our validation function `checkPasswords`.

checkPasswords(group: FormGroup){

  let pass = group.get(‘password’).value;
  let confirmPass = group.get(‘confirm_password’).value;
  return pass === confirmPass ? null : { notSame : true }

}

The method will take a FormGroup instance as a parameter, perform your custom checks on the group’s controls, and then return either null if the form group is valid, or else an object setting your custom error to true. In our case above, if the `password` control’s value is different from the `confirm_password` control’s value, a ‘notSame’ (arbitrary name, you could make up your own) error will be trigerred on the form.

We will then update our form’s initialization code to use our new validator :)

this.cvForm = this.fBuilder.group({

  email: [‘’, Validators.required],
  password: [‘’, Validators.required],
  confirm_password: [‘’],
  rating: [0, Validators.required],
  skill_name: [‘’, Validators.required]

}, { validators: this.checkPasswords })

But, something’s different here. We are not setting the validator directly on the form control but after the definition. Why would that be?

Well to put it simply, our checkPasswords validator cannot be bound to a single form control because we are using values from 2 different controls inside its logic. It therefore needs to be applied at the FormGroup level.

We will also add a “createCV” method that we will trigger on form submission. for now it will just log the whole form value to the console.

Here is what our final cv.component.ts will look like:

Almost done! now let’s look at the markup.

Step 7. HTML

Inside our component’s template file (cv.component.html), we will now need to write the markup for our form. The page structure and styling aside, here are the important parts we will need to include in our markup:

<form [formGroup]=”cvForm”>
   …
</form>

Firstly the form tag. as shown above, we can bind it to the formgroup created in our component ts file using the [formGroup] directive.

Next, let’s look at how to add our form controls. we will take the email field as en example:

<input type="text" formControlName="email" class="form-control" placeholder="Please enter your Email" />

By usingthe formControlName directive and binding it to our form control name defined in our ts file, we have now bound this html input tag to our form control object. We can even change its attributes depending on the formcontrol’s status:

<input type=”text” formControlName=”email” class=”form-control” placeholder=”Please enter your Email” [ngClass]=”{‘is-invalid’: cvForm.controls.email.dirty && cvForm.controls.email.invalid}” />

Now our input will have a class of “is-invalid” whenever the formControl’s validator(s) fail. You will notice that, in addition to checking for validity, we are checking a property of our control called “dirty”.

cvForm.controls.email.dirty

What this property does is, returns true if and only if the form control’s value has been changed by the user since the form was loaded. This will prevent us from getting errors caused by the initially empty required fields.

What if we needed to display an error message to the user in case the form was invalid? Well we already know the condition to use and can just use an *ngIf to handle it :)

<div class="is-invalid text-danger mt-1" *ngIf="cvForm.controls.email.dirty && cvForm.controls.email.invalid">Email is required!</div>

And it is done!

We can now repeat this logic for all our form fields, so that all controls have a corresponding input.

Step 8. The submit button

The last part we will look at now is the form’s submit button. let’s take a look at the button tag below:

<button class="btn btn-sm btn-outline-dark mr-2" (click)="createCv()">
  <i class="fa fa-envelope mr-2"></i> Save CV
</button>

On click of this button, we are going to call our createCv method. But what if we wanted the button to be disabled when our form was in an invalid state?

<button class="btn btn-sm btn-outline-dark"  [disabled]="cvForm.invalid" (click)="createCv()">
   <i class="fa fa-envelope mr-2"></i> Save CV
</button>

The Submit button will now be disabled whenever cvForm is in an invalid state.

Our final cv.component.html file, with added markup for style and formatting, will be as follows:

We now have a basic form with validation. The next part we will be looking at how to implement custom form controls.

Neat! now we can submit the form, or store the values in our localStorage, or whatever our requirements dictate :)

In the next part of this series we will be looking at how to create custom form controls outside of those provided natively by our browser.

Until then, Stay safe and keep learning ^^

Note: Ceci est une traduction d’un de mes articles en Anglais ici

Il y a quelques semaines lors d’une de mes sessions de formation, l’une de mes sessions de formation, un de mes élèves travaillant sur un projet Angular devait implémenter un composant d’upload de fichiers en glisser/déposer.

Comme probablement tout développeur, son premier réflexe était de chercher un plugin existant sur npm, mais en l’aidant à externaliser et personnaliser l’aspect visuel du plugin je me suis dit que c’était en fait une belle opportunité de démystifier l’implémentation d’une fonctionnalité de cette envergure, en l’aidant à créer son propre composant :) Cet article est le résumé du résultat de cette session de travail.

Dans notre cas, nous avions déjà un projet Angular sur lequel travailler. Cependant, afin que cet article puisse être suivi indépendamment, nous allons commencer par créer un squelette d’application générique.

Comme dans mon dernier article je pars du principe que vous avez déjà l’outil CLI du framework Angular d’installé sur votre machine. Si tel n’est pas le cas vous pouvez jeter un œil sur la doc :)

( https://angular.io/guide/setup-local )

Step 1: Création du projet

Dans un invite de commande, entrez la commande suivante:

ng new angular-file-upload --style=scss

Step 2: Générer une nouvelle directive qui contiendra notre logique pour le glisser/déposer.

Les directives en Angular sont des fonctions qui améliorent les capacités des éléments HTML en y rattachant de la logique via des balises et/ou attributs personnalisables. Voyons ce que cela donne concrètement.

Nous allons tout d’abord changer de dossier pour aller a la racine de notre projet

cd angular-file-upload

Nous pouvons ensuite générer notre directive avec le CLI Angular

ng g directive directives/upload

Cette commande va créer le fichier upload.directive.ts comme tel:

import { Directive } from ‘@angular/core’;

@Directive({
  selector: ‘[appUpload]’
})

export class UploadDirective {
  constructor() { }
}

Cette classe sera notre directive. Nous pouvons déjà noter ici la ligne “selector: [‘appUpload’]”. Cette ligne signifie en gros que, tout élément (ou tag) dans le DOM auquel nous attacherons l’attribut “appUpload” va hériter de la logique que nous allons définir dans cette classe. Nous pouvons aussi changer le nom du sélecteur mais pour cette démo on va la laisser tranquille :)

Step 3: Import des composants de notre directive

Angular étant un framework très complet à la base, nous avons déjà tout ce dont nous avons besoin pour implémenter notre fonctionnalité, et n’aurons besoin d’aucune dépendance externe. Nous aurons juste à importer quelques décorateurs depuis @angular/core

Nous allons maintenant changer la ligne d’import de notre directive comme suit:

import { Directive, Output, EventEmitter, HostBinding, HostListener, HostBindingDecorator } from ‘@angular/core’;

Jetons un œil sur les nouvelles additions. Nous avons donc:

• Output et EventEmitter seront utilisés afin d’exposer un évènement auquel notre composant pourra réagir. En effet, notre composant devra pouvoir réagir au drop d’un fichier.
• HostBinding permet d’interagir avec les propriétés de l’élément DOM auquel notre directive sera rattachée (le Host) Dans notre cas nous allons uniquement interagir avec l’attribut “style”
• et HostListener permet d’écouter et réagir aux évènements DOM de notre élément Host.

Step 4: Définir les propriétés de notre classe directive.

Dans la définition de notre Classe, nous allons tout d’abord rajouter trois propriétés en utilisant nos décorateurs Output et HostBinding définis plus haut:

@Output() onFileDropped = new EventEmitter<any>();
@HostBinding(‘style.background-color’) public background = ‘#fff’;
@HostBinding(‘style.opacity’) public opacity = ‘1’;

Ces trois propriétés vont nous permettre de contrôler notre directive.

• OnFileDropped sera l’événement que notre directive exposera a notre component, d’ou le decorateur Output. Nous lancerons l’événement OnFileDropped quand un fichier sera déposé sur notre élément Host.
• background et opacity sont de simple variables que nous rattachons ici à la propriété “style” de notre élément Host. Notez que nous définissons aussi par défaut une couleur (blanc) et une opacité complète.

Si nous rattachons maintenant notre directive à un élément DOM dans notre component, rien ne va se passer, à part le fait que la couleur et l’opacité seront aux valeurs définies plus haut.

Nous pouvons maintenant rajouter un peu de logique à notre directive :)

Step 5: Les évènements DOM

Nous allons commencer par ajouter deux méthodes à notre Classe, qui réagiront aux évènements DOM dragOver et dragLeave. Dans ces méthodes, nous allons simplement changer la couleur et l’opacité de notre élément, et en empêcher la propagation :)

//Dragover, l'utilisateur glisse quelque chose sur notre élément
Host element
@HostListener(‘dragover’, [‘$event’]) onDragOver(evt) {
  evt.preventDefault();
  evt.stopPropagation();
  this.background = ‘#9ecbec’;
  this.opacity = ‘0.8’
}

//Dragleave, l'utilisateur glisse quelque chose hors de notre élément Host
@HostListener('dragleave', ['$event']) public onDragLeave(evt) {
  evt.preventDefault();
  evt.stopPropagation();
  this.background = '#fff'
  this.opacity = '1'
}

Step 6: L’évènement drop

On y est presque! nous devons maintenant ajouter notre dernière méthode, qui réagira quand l’utilisateur dépose un fichier sur notre élément.

@HostListener('drop', ['$event']) public ondrop(evt) {
  evt.preventDefault();
  evt.stopPropagation();
  this.background = '#f5fcff'
  this.opacity = '1'
  let files = evt.dataTransfer.files;
  if (files.length > 0) {
    this.onFileDropped.emit(files)
  }
}

Cette méthode est quelque peu différente, Outre les deux premières lignes pour empêcher la propagation, et le changement de style, ici nous vérifions si ce qui a été déposé sur notre Host est effectivement un fichier, et si tel est le cas nous lancerons notre évènement onFileDropped, auquel notre component pourra réagir è son tour.

Et nous avons fini notre directive! ;) voici le code complet:

import { Directive, Output, EventEmitter, HostBinding, HostListener, HostBindingDecorator } from '@angular/core';

@Directive({
  selector: '[appUpload]'
})

export class UploadDirective {

@Output() onFileDropped = new EventEmitter<any>();
@HostBinding('style.background-color') public background = '#fff';
@HostBinding('style.opacity') public opacity = '1';
  
  //Dragover, l'utilisateur glisse quelque chose sur notre élément
Host element
  @HostListener('dragover', ['$event']) onDragOver(evt) {
    evt.preventDefault();
    evt.stopPropagation();
    this.background = '#9ecbec';
    this.opacity = '0.8'
  };

//Dragleave, l'utilisateur glisse quelque chose hors de notre élément Host
  @HostListener('dragleave', ['$event']) public onDragLeave(evt) {
    evt.preventDefault();
    evt.stopPropagation();
    this.background = '#fff'
    this.opacity = '1'
  }

  @HostListener('drop', ['$event']) public ondrop(evt) {
    evt.preventDefault();
    evt.stopPropagation();
    this.background = '#f5fcff'
    this.opacity = '1'
    let files = evt.dataTransfer.files;
    if (files.length > 0) {
      this.onFileDropped.emit(files)
    }
  }

  constructor() { }

}

Step 7: Utilisation de notre nouvelle directive

Une fois notre directive implémentée, nous pouvons l’inclure dans notre component. Dans notre cas nous utilisons le app Component pour faire simple, mais nous pouvons faire la même chose dans n’importe quel component de notre application.

Dans notre app.component.html, nous allons rajouter l’élément suivant:

<div appUpload (onFileDropped)="uploadFile($event)" >Déposer un fichier ici</div>

Notre étape finale sera de réagir a notre onFileDropped depuis notre app.component.ts en y ajoutant la méthode uploadFile

uploadFile(evt){
// evt est un tableau des fichier(s) déposés sur notre div. Ici nous supposerons qu'il y a un seul fichier uploadé
  
  let payload = new FormData();
  payload.append('data', evt[0]);
  // Nous pouvons maintenant uploader le fichier en lancant une requete POST avec la variable payload comme corps de requete :)
}

Nous sommes maintenant libres de personnaliser notre interface utilisateur à volonté avec du CSS :)

Lors de mes séances de formation, j’essaie beaucoup de démystifier l’implémentation d’éléments UI communs. J’ai pu remarquer au fil des sessions que les nouveaux développeurs ont tendance à traiter les “UI packs” ou composants JavaScript tout prêts comme des boites noires, et leur montrer qu’avec leurs aptitudes actuelles ils peuvent coder une telle fonctionnalité les aide a prendre confiance en eux et démontrer leur créativité :)

J’ai également ajouté du CSS pour rendre la démo un peu plus “user friendly”. Vous pourrez trouver le code de cette démo ici.

Une live démo peut aussi être trouvée ici.

In this 2-part series, we are looking at how to implement directives in Angular. In this first part we will be looking at attribute directives. And in part 2 we will be looking at structural directives.

Recently, during one of my training sessions, one of my trainees working on an Angular project needed to implement a drag and drop file upload component.

So as is often the first reflex, they looked for an existing npm package that does the task, but ran into issues with making the new packages feel coherent with the rest of the application’s UI.

After helping them dig around for a way to customize the CSS however, I had a thought. What if I used this situation as an opportunity to build their understanding of custom directives, and by the same occasion demystify the implementation of such a functionality by showing them they could easily build it themselves? This blog post as basically what we ended up with.

So we already had an existing Angular project initialized, but for the sake of this blog post being its own independent thing if you are following through, we will here create a generic app skeleton to demo this.

As in my previous blog post I am assuming that you already have the Angular cli installed here. (If not, please check out this guide to install the tooling: Angular — Setting up the local environment and workspace https://angular.io/guide/setup-local )

Step 1: Creating our standalone project

Run the following command in your terminal

ng new angular-file-upload --style=scss

Step 2: Generating a new directive that will contain our logic for the drag and drop file upload.

Angular directives are functions that enhance the capability of HTML elements by attaching custom behavior to the DOM via custom tags and attributes. What does this mean concretely? Let’s have a look.

First we need to change directory to our project folder

cd angular-file-upload

Then we can generate our brand new directive using the angular CLI

ng g directive directives/upload

This shall create the following upload.directive.ts file:

import { Directive } from ‘@angular/core’;

@Directive({
  selector: ‘[appUpload]’
})

export class UploadDirective {

constructor() { }

}

So basically this class will be our directive. Worthy of note already in that skeleton is the selector in the directive declaration. In a nutshell, this means that any DOM element we attach the “appUpload” attribute to will have additional behaviour that we will defined in this class. We can also change the selector if we wish, but for the purpose of this demo we shall leave it be :)

Step 3: Importing the pieces we need

Part of the beauty of Angular is that the framework comes with many parts already included, so we won’t have any external dependency for this functionality and only use what is provided to us in @angular/core.

Update the import line in our directive to read as follows:

import { Directive, Output, EventEmitter, HostBindingDecorator, HostListener } from ‘@angular/core’;

So if we go over the new additions, we now have:

• Output and EventEmitter will be used to provide a hook event our component will be able to subscribe to. This is important since we need the component to be able define what happens when a file is dropped.
• HostBindingDecorator will allow us to interact with the properties of the DOM element our directive will be attached to. In our case we will interact with the style of the host element
• and HostListener will allow us to listen to DOM events from the host element and define how our directive will react to them.

Step 4: Define our Class properties

Within our Class definition, we will first add three properties using our Output and HostBindingDecorator as follows:

@Output() onFileDropped = new EventEmitter<any>();
@HostBinding(‘style.background-color’) public background = ‘#fff’;
@HostBinding(‘style.opacity’) public opacity = ‘1’;

Here we have the properties that will help us control the directive.

• OnFileDropped will be the custom event that we will expose to our component, thus the output decorator. This will be triggered when a file is dropped on our host DOM element later.
• background and opacity on the other hand are simple properties that we are binding to the host DOM element’s style property. We are also setting the default “idle” values to a white background and a full opacity.

As of now, if we try to attach our directive to a DOM element, nothing much will happen, only the element’s background color and opacity will be affected. So now would be the perfect time to add some more behaviour to our directive :)

Step 5: Adding the drag events

We will now add two methods to our class, which will be event listeners for our dragOver and dragLeave events. In these methods, we will simply change the background and opacity defined above, and prevent those events from bubbling up to our host component.

//Dragover listener, when something is dragged over our host element

@HostListener(‘dragover’, [‘$event’]) onDragOver(evt) {
  evt.preventDefault();
  evt.stopPropagation();
  this.background = ‘#9ecbec’;
  this.opacity = ‘0.8’
}

//Dragleave listener, when something is dragged away from our host element

@HostListener('dragleave', ['$event']) public onDragLeave(evt) {
  evt.preventDefault();
  evt.stopPropagation();
  this.background = '#fff'
  this.opacity = '1'
}

Step 6: Our drop event

Almost done with the directive! all that’s left is to add our last event listener, for when a file is actually dropped over our host DOM element. Let’s add the following method:

@HostListener('drop', ['$event']) public ondrop(evt) {
  evt.preventDefault();
  evt.stopPropagation();
  this.background = '#f5fcff'
  this.opacity = '1'
  let files = evt.dataTransfer.files;
  if (files.length > 0) {
    this.onFileDropped.emit(files)
  }
}

This one is a bit different. Apart from the similar bubbling prevention and style alterations, here we are checking if there are actually files that were dropped on our host DOM element, and if such is the case we emit our custom onFileDropped event that can be subscribed to from our component.

We have now completed our directive. here is the complete Class definition:

import { Directive,Output, EventEmitter, HostBinding, HostListener, HostBindingDecorator } from '@angular/core';

@Directive({
  selector: '[appUpload]'
})

export class UploadDirective {

  @Output() onFileDropped = new EventEmitter<any>();
  @HostBinding('style.background-color') public background = '#fff';
  @HostBinding('style.opacity') public opacity = '1';
  
  //Dragover listener, when something is dragged over our host element
  @HostListener('dragover', ['$event']) onDragOver(evt) {
    evt.preventDefault();
    evt.stopPropagation();
    this.background = '#9ecbec';
    this.opacity = '0.8'
  };

  //Dragleave listener, when something is dragged away from our host element
  @HostListener('dragleave', ['$event']) public onDragLeave(evt) {
    evt.preventDefault();
    evt.stopPropagation();
    this.background = '#fff'
    this.opacity = '1'
  }

  @HostListener('drop', ['$event']) public ondrop(evt) {
    evt.preventDefault();
    evt.stopPropagation();
    this.background = '#f5fcff'
    this.opacity = '1'
    let files = evt.dataTransfer.files;
    if (files.length > 0) {
      this.onFileDropped.emit(files)
    }
  }

  constructor() { }

}

Step 7: Using the directive

Now that our directive has been implemented, we can include it in our component. It can be any component in your app, but for the purpose of this demo we will be using the main app component.

In our app.component.html file let’s add the following element:

<div appUpload (onFileDropped)="uploadFile($event)" >Drop a file here</div>

Our final step will be to handle the onFileDropped event within our app.component.ts by defining the uploadFile method.

uploadFile(evt){
  // evt is an array of the file(s) dropped on our div. Here we're assuming only one file has been uploaded
  
  let payload = new FormData();
  payload.append('data', evt[0]);
  // File can now be uploaded by doing an http post with the payload
}

From there we can proceed with tweaking the UI as desired to fit our requirements :)

During my training sessions, one of my main objectives is to help demystify the implementation of common UI components to my trainees. It has been my observation that Junior devs tend to treat ready-made UI components as black boxes and demonstrating how they themselves could implement such a component from scratch helps them realize the realm of possibilities at their fingertips :)

I have also added some CSS to make the demo a bit more user friendly. As usual all the code for this demo can be found at: Angular file upload.

The UI for this demo can be found at Angular upload file.

Creating a Drag and Drop File Upload Component Using Angular Directives was originally published in The Startup on Medium, where people are continuing the conversation by highlighting and responding to this story.

I’ve recently heard some noise online about a new toy called Tailwind CSS. Well after playing around with Bootstrap, discovering Sass and overall messing around with preprocessors / CSS frameworks, how could I miss the chance to try a shiny new toy? :)

Meanwhile, I have been developing production web (and mobile) apps using Angular, so I told myself, the best way to try if Tailwind would fit in my existing workflow would be to try integrating it directly in there right? So that’s exactly what I did.

Let’s take a quick look at the main actors in our little experiment first.

What is Tailwind CSS?

Well, given that I’m just getting started with Tailwind, you’d probably learn more about Tailwind on the official website (See What is Tailwind ), but if you want my quick shot at a description, Tailwind CSS is a minimalist utility first, highly customizable, low-level CSS framework. What does that mean? In short, Tailwind allows you to create beautiful custom UI elements without making any design choices for you.

Since this article is about integrating Tailwind with Angular, a more in depth description would be out of place here, but feel free to check the Official website :)

What is Angular:

Angular is a platform and framework for building single-page client applications. Angular is written in TypeScript and… Wait, you actually don’t know Angular? Please check the official website: Angular framework

I’ve started working with the Angular framework since 2016, and haven’t looked back. Try it! You may come to love it too! 😜

Now let setup our first demo project. I am assuming that you already have the Angular cli installed here. (If not, please check out this guide to install the tooling: Angular — Setting up the local environment and workspace )

Set up Angular project:

Step 1: Create Angular project

First we’ll begin by creating our skeleton project in which we’ll try to integrate Tailwind. We’ll call the project “angular-tailwind-demo”, because what’s more beautiful than a completely explicit name? :)

Run the following command in your console:

ng new angular-tailwind-demo --style=scss

Step 2: Add Tailwind to the project

Next, once we have our generated project boilerplate, we’ll add the Tailwind package using npm.

cd angular-tailwind-demo

npm install tailwindcss --save

Step 3: Initiate a Tailwind config

Ok, now we have everything we need to start our little experiment ^^. We’ll begin by initializing Tailwind.

npx tailwindcss init

The default init will create a minimal tailwind.config.js file and place it at the root folder of your project. This file will look something like the following:

// tailwind.config.js

module.exports = {
  theme: {},
  variants: {},
  plugins: [],
}

Our next step here will be to customize the generated config file to fit our needs.

Below is an example of a customized tailwind.config.js

// Example `tailwind.config.js` file

module.exports = {
 important: true,
 theme: {
  fontFamily: {
    display: ['Gilroy', 'sans-serif'],
    body: ['Graphik', 'sans-serif'],
  },
  extend: {
    colors: {
      cyan: '#9cdbff',
    },
    margin: {
     '96': '24rem',
     '128': '32rem',
    },
   }
 },
 variants: {
  opacity: ['responsive', 'hover']
 }
}

Every section of the config file is optional and only needs to specify what needs to change. For example the tailwind.config.js file above defined the font-family in the theme section, as well as the colors, margin and padding in the extend section. Any missing part will fallback to default configuration.

Step 4: Create a tailwind-build.css inside your src project folder and configure it as shown below:

@tailwind preflight;
//Your custom components go here...

@tailwind utilities;
// Your custom utilities go here...

According to the Tailwind official documentation, Preflight is a set of base styles for Tailwind projects that are designed to smooth over cross-browser inconsistencies and make it easier for you to work within the constraints of your design system.

Tailwind also provides a pretty comprehensive set of utility classes out of the box.

Step 5: Add this script to your package.json file, inside the script block as follows:

"scripts": {
...
"tailwind": "./node_modules/.bin/tailwind build ./src/tailwind-build.css -c ./tailwind.config.js -o ./src/styles.css",
"prestart": "npm run tailwind",
}

Next: in your angular.json file, in “architect”, “options”, “styles” add “src/styles.css”

"prefix": "app",
"architect": {
  "build": {
    "builder": "@angular-devkit/build-angular:browser",
    "options": {
      "outputPath": "dist/angular-tailwind-demo",
      "index": "src/index.html",
      "main": "src/main.ts",
      "polyfills": "src/polyfills.ts",
      "tsConfig": "tsconfig.app.json",
      "aot": true,
      "assets": [
        "src/favicon.ico",
        "src/assets"
      ],
      "styles": [
        "src/styles.scss",
        "src/styles.css"
      ],
      "scripts": []
    },
    ...
   }
  }

Step 6: Let’s create a card component by running the following in our terminal

ng generate component card

This command should generate a few files for our components. Of interest to us here is mostly the template card.component.html file.

Next let’s add our UI markup in the generated card.component.html.

<div class="flex flex-wrap mt-4 mb-4">
  <div class="w-full md:w-1/2 lg:w-1/3 pr-3" *ngFor="let car of carFilterList">
    <div class="card">
      <img class="object-cover h-56 w-full" [src]="car.car_image" alt="{{car.name}}">
      <div class="px-6 py-4">
       <div class="font-bold text-gray-700 text-xl mb-2">{{car.name}}</div>
       <p class="text-gray-700 text-base">
        Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptatibus quia, nulla!
       </p>
     </div>
     <div class="px-4 py-4 flex">
      <span class="inline-block cursor-pointer bg-gray-200 rounded-full px-3 py-1 text-sm font-semibold text-gray-700 mr-2" [routerLink]="[car.car_url]">
      <i class="fa fa-angle-double-right"></i>
      View list
     </span>
   </div>
  </div>
 </div>
</div>

We are using a few classes provided by Tailwind here. A few examples are:
 — “w-full” class will make the element take a width of 100%.
 — “md:w-1/2” to an element would set the element width of 50% at medium screen sizes and above.
 — “text-gray-700” Control the text color of an element using the .text-{color} utilities.

These are Tailwind utility classes and will be processed by Tailwind to generate our CSS.

After creating the card component, let’s add some styling. In our tailwind-build.css let’s add some style under @tailwind components;

For components like card and form elements, creating a template partial or JavaScript component can often feel too heavy compared to a simple CSS class.

In these situations, you can use Tailwind @apply directive to easily extract common utility patterns to CSS component classes.

Here’s what a .card class might look like using @apply to compose it from existing utilities:

@tailwind components;

.card {
  @apply max-w-sm rounded overflow-hidden shadow mt-4
}

.card:hover {
  @apply shadow-lg
}

Now just using the card class will apply all these utility classes to our element, thanks to @apply

Step 7: Let’s import our card component in our app.component.html by including this tag

<app-card></app-card>

Step 8: We can now run the following code in the terminal to check if everything is working as expected

ng serve --open

If all goes well, this should open a browser window pointing to http://localhost:4200 which should display our card component.

Now we can use the card component anywhere in our application.

Summary, or What have we learned so far?

• We created a new Angular project and installed the Tailwind CSS package
• We looked at the config files required for Tailwind to work
• We created a card component with minimal lines of actual CSS.

Playing around with Tailwind is pretty straightforward and the rapidly growing community around the framework looks friendly and ready to help in case of issues.

I will definitely look into it more, and maybe eventually use it in production :)

Do you have experience using Tailwind CSS in conjunction with a JavaScript framework? Let me know in the comment! :)

For a more in depth preview of what is possible with Tailwind, here’s a demo app extending the concept component explored in this article: Angular Tailwind demo.

The UI for this demo can be found at Market place.