DEV Community: Camilo Muñoz

Building a Reusable MultiCheck Field in Angular

Camilo Muñoz — Thu, 10 Sep 2020 06:01:08 +0000

It's quite common to have forms where the user can select many options from several available:

The most popular way to tackle this in Angular is by using a set of <input type="checkbox"> with a FormArray. However, when the same functionality is required in several forms across the application, it's highly possible we start repeating lots of code, for both the logic and the markup.

In this post we will address this issue by building a component that has the following features:

MultiCheck: several options can be selected simultaneously
Reusable: the options can be presented with different visual implementations without re-writing the logic
Custom Field: tailored form field that works directly with Angular Forms

Once we are done, we could use the component to build forms that behave like this:

Design
Step 1: Supporting a SimpleCheckOption Component
Step 2: Supporting Any Kind of Option Component
Step 3: Integration with Angular Forms
Final Words
Demo
Further Improvement
Code Repository Links

Design

Our component will be composed by two elements:

The field component, which keeps track of the selected options and provides the integration with AngularForms.
The option component, which represents a single check option and provides the visual implementation for it. The idea is that we have several of this kind.

Step 1: Supporting a SimpleCheckOption Component

We will start by supporting only a simple-check-option by our multi-check-field, but keeping in mind that we want the field to be used with any option component.

That being said, we'll use Content Projection to provide the desired options to the multi-check-field, like this:

<multi-check-field>
    <simple-check-option *ngFor="let option of options" [value]="option"
      [label]="option.label">
    </single-check-option>
</multi-check-field>

Note how Content Projection is used by passing the options inside the enclosing tags of the multi-check-field.

Now, let's see the implementation of the simple-check-option:

@Component({
  selector: 'simple-check-option',
  template: `
    <label>
      <input type="checkbox" [formControl]="control">
      {{ label }}
    </label>
  `
})
export class SimpleCheckOptionComponent {

  @Input() value: any;
  @Input() label: string;

  public control = new FormControl(false);

  get valueChanges$(): Observable<boolean> {
    return this.control.valueChanges;
  }

}

The component has a standard <input type="checkbox"> with it's label. We also declare a FormControl to manipulate the checkbox value and, additionally, we provide a valueChanges$ accessor so we can interact with the component with type safety from the outside.

The multi-check-field component will use the ContentChildren decorator to query the projected options:

@Component({
  selector: 'multi-check-field',
  template: `<ng-content></ng-content>`
})
export class MultiCheckFieldComponent implements AfterContentInit {

  @ContentChildren(SimpleCheckOptionComponent)
  options!: QueryList<SimpleCheckOptionComponent>;

  ngAfterContentInit(): void {
    // Content query ready
  }

}

It's worth to be noted that the content query will first be ready to be used in the AfterContentInit lifecycle, but not before. Additionally, see how we use the <ng-content> tags in the component's template to render there the provided content (the options).

Now, let's see how we keep track of the selected options

private subscriptions = new Subscription();
private selectedValues: any[] = [];

ngAfterContentInit(): void {
  this.options.forEach(option => {
    this.subscriptions.add(
      option.valueChanges$.subscribe(
        (optionChecked) => {
          if (optionChecked) {
            this.add(option.value);
          } else {
            this.remove(option.value);
          }
        }
      )
    );
  });
}

private add(value: any): void {
  this.selectedValues.push(value);
}

private remove(value: any): void {
  const idx = this.selectedValues.findIndex(v => v === value);
  if (idx >= 0) {
    this.selectedValues.splice(idx, 1);
  }
}

We use the option's valueChanges$ accessor to subscribe to the event when an option is checked/unchecked. Depending on the optionChecked boolean value, we then proceed to add or remove this option from our selectedValues array.

At this point, our multi-check-field is fully integrated with the simple-check-option. But we should take advantage of Angular's Content Projection to be able to support any kind of component as a check-option. Let's see how.

Step 2: Supporting Any Kind of Option Component

Let's create a new option component that looks very different to the simple-check-option but has the same functionality. We'll name it user-check-option and it will represent... well, an user 😅.

The component logic is basically the same that we have in simple-check-option, but the template has considerable differences:

@Component({
  selector: 'user-check-option',
  template: `
    <label>
      <input type="checkbox" [formControl]="control">
      <div class="card">
        <div class="avatar">
          <img src="assets/images/{{ value.avatar }}">
          <div class="span"></div>
        </div>
        <h1>{{ value.name }}</h1>
        <h2>{{ value.location }}</h2>
      </div>
    </label>
  `
})
export class UserCheckOptionComponent {

  @Input() value: any;

  public control = new FormControl(false);

  get valueChanges$(): Observable<boolean> {
    return this.control.valueChanges;
  }

}

To support our new user-check-option by the field component, we have to modify the ContentChildren query, given that we are not targeting exclusively a SimpleCheckOption anymore. This is the query we currently have:

@ContentChildren(SimpleCheckOptionComponent)
options!: QueryList<SimpleCheckOptionComponent>;

Unfortunately, we cannot use ContentChildren to target two different kind of components, but we can use the power of Angular's Dependency Injection (DI) to overcome this situation.

Dependency Injection to the Rescue 👨‍🚒 👩‍🚒 🚒

One possible solution for this issue would be to use alias providers to create a common DI token to be employed by our option components.

abstract class MultiCheckOption { }                        // (1)

@Component({
  selector: 'simple-check-option',
  providers: [
    {                                                      // (2)
      provide: MultiCheckOption,
      useExisting: SimpleCheckOptionComponent,
    }
  ]
})
export class SimpleCheckOptionComponent { ... }

@Component({
  selector: 'user-check-option',
  providers: [
    {                                                      // (3)
      provide: MultiCheckOption,
      useExisting: UserCheckOptionComponent
    }
  ]
})
export class UserCheckOptionComponent { ... }

We start by creating a MultiCheckOption class to be used as DI token by our option components.
We configure the injector at the component level of our SimpleCheckOptionComponent by using the providers metadata key. With this configuration, when Angular's DI ask our component's injector for an instance of MultiCheckOption, it would pass the existing instance of the component itself.
We do the same for the UserCheckOptionComponent.

The ContentChildren query could now be rewritten as:

@ContentChildren(MultiCheckOption)
options!: QueryList<MultiCheckOption>;

But we are not finished yet... at this point we lost access to the members and methods of the option components, since the MultiCheckOption class is empty. We can fix this by using the class itself to hold what is common among the options and expose what necessary. After that, we take advantage of ES6 class inheritance to extend the option components from MultiCheckOption.

export abstract class MultiCheckOption {
  abstract value: any;
  public control = new FormControl(false);
  get valueChanges$(): Observable<boolean> {
    return this.control.valueChanges;
  }
}

@Component(...)
export class SimpleCheckOptionComponent extends MultiCheckOption {
  @Input() value: any;
  @Input() label: string;
}

@Component(...)
export class UserCheckOptionComponent extends MultiCheckOption {
  @Input() value: any;
}

And just like that, the multi-check-field supports now any component that implements the MultiCheckOption logic.

Step 3: Integration with Angular Forms

At this stage, you might try to use the multi-check-field with Angular Forms

<multi-check-field formControlName="subjects">
    ...
</multi-check-field>

But then, you will get the following error:

No value accessor for form control with name: 'subjects'

The reason is, the AngularFormsModule only knows how to deal with native form elements (like <input> and <select>). In order for our custom multi-check-field to work with Angular Forms, we'll have to tell the framework how to communicate with it. (If this is the first time you hear about custom form fields in Angular, I would recommend you to check this post.

1. The `NG_VALUE_ACCESSOR` Provider

We start by registering the component with the global NG_VALUE_ACCESSOR provider:

import { Component, forwardRef } from '@angular/core';
import { NG_VALUE_ACCESSOR } from '@angular/forms';

@Component({
  selector: 'multi-check-field',
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: forwardRef(() => MultiCheckFieldComponent),
      multi: true
    }
  ]
})
export class MultiCheckFieldComponent { ... }

2 . The `ControlValueAccesor` Interface

Additionally, we need to implement the ControlValueAccesor interface, which defines the following set of methods to keep the view (our component) and the model (the form control) in sync.

writeValue(obj: any): void;
registerOnChange(fn: any): void;
registerOnTouched(fn: any): void;
setDisabledState?(isDisabled: boolean): void;

writeValue(obj: any)

This function is executed by the framework to set the field value from the model to the view. For example, when performing any of the following actions.

multiCheckControl = new FormControl(TEST_INITIAL_VALUE);
multiCheckControl.setValue(TEST_VALUE);
multiCheckControl.patchValue(TEST_VALUE);

In our case, the obj parameter should be an array containing the selected options values. We better name it values for improved readability.

writeValue(values: any[]): void {
    this.selectedValues = [];
    values = values || [];
    values.forEach(selectedValue => {
      const selectedOption = this.options.find(v => v.value === selectedValue);
      selectedOption.control.setValue(true);
    });
}

Each item of the values array is mapped to the corresponding option, and then the checked value is reflected in it's view (in our example, this is done yet through another control).

Note that every time we call selectedOption.control.setValue(), the corresponding valueChanges$ subscription declared in ngAfterContentInit is called and the option's value gets added to the local selectedValues array.

Let's see it working

@Component({
  selector: 'app-root',
  template: `
    <multi-check-field [formControl]="multiCheckControl">
      <simple-check-option *ngFor="let subject of subjects"
        [value]="subject" [label]="subject.label">
      </simple-check-option>
    </multi-check-field>
    <button (click)="setTestValue()">Set Test Value</button>
    Control value: <pre>{{ multiCheckControl.value | json }}</pre>
  `,
})
export class AppComponent {

  public subjects = [
    { code: '001', label: 'Math' },
    { code: '002', label: 'Science' },
    { code: '003', label: 'History' },
  ];

  public multiCheckControl = new FormControl();

  setTestValue() {
    const testValue = [this.subjects[0], this.subjects[1]];
    this.multiCheckControl.setValue(testValue);
  }

}

registerOnChange(fn: any)

Registers the function that needs to be called when the field value changes in the UI. When the provided function is called, it will update the value from the view to the model.

In our case, we have to update the model value every time an option is checked/unchecked.

export class MultiCheckFieldComponent implements ControlValueAccessor {

  _onChange: (_: any) => void;

  registerOnChange(fn: any): void {
    this._onChange = fn;
  }

  private add(value: any): void {
    this.selectedValues.push(value);
    this._onChange(this.selectedValues);
  }

  private remove(value: any): void {
    const idx = this.selectedValues.findIndex(v => v === value);
    if (idx >= 0) {
      this.selectedValues.splice(idx, 1);
      this._onChange(this.selectedValues);
    }
  }
  ...
}

registerOnTouched(fn: any)

In the same way as the previous method, we need to register the function to be called when the field is touched, in order for the control to trigger validation and more.

We will leave the implementation of this method out of the scope of this tutorial.

setDisabledState?(isDisabled: boolean)

Last but no least, the setDisabledState method. This function is called when the field is enable/disabled programmatically. For example, when the following actions are performed:

multiCheckControl = new FormControl({
  value: TEST_INITIAL_VALUE,
  disabled: true
});
multiCheckControl.disabled();
multiCheckControl.enabled();

This method will also be left out of the scope of the tutorial.

Final Words

We managed to create a component that provides a multi-check functionality but also offers:

Reducing of code duplication, given that all the logic is encapsulated within the component and doesn't need to be re-written for every form.
Simplicity, since the usage is pretty straightforward. Very similar to a native <select> with <option> tags inside.
Reusability, because the options can be styled as desired.
Compatibility, considering that it supports integration with Angular Forms.

Demo Time 🌋

Further Improvement

There is still a lot of room for improvement. I list here some ideas in case you want to code a bit. Don't hesitate to open a PR to integrate your solution to the repository:

Support a value passed on initialization (writeValue executed before ngAfterContentInit) ✅
Support changes in the projected options (when they are added or removed from DOM)
Support registerOnTouched and setDisableState methods
Write a minValuesLength and maxValuesLength validators
Support passing a template as an option instead of a component

Code Repository Links

The full source code can be found here
In this branch, you can find the implementation for some of the improvements suggested above

Using RxJS Timer to Provide Periodic Async Data

Camilo Muñoz — Tue, 18 Aug 2020 22:37:53 +0000

In my last project, our team needed to create a real time bid system where the user had the ability to bid for contracts for a given period of time. The remaining time for each contract would be displayed as a countdown, like this:

In this post I’ll show the different approaches we took to solve this challenge, and why the rxjs implementation was the most convenient in our case.

Solution #1: The Countdown Component ⏲️

We could have easily declared a countdown component with the expiration date as an input and run a setInterval that updates the remaining time every second.



@Component({
  selector: 'app-countdown',
  template: '<span>{{ remainingTime }}</span>',
})
export class CountdownComponent implements OnInit {
  @Input() expireDate: Date;
  public remainingTime: string;

  ngOnInit(): void {
    setInterval(() => {
      this.remainingTime = this.calculateRemainingTime(this.expireDate);
    }, 1000);
  }
}

This implementation is simple and very easy to implement, but it has some disadvantages:

Each countdown is independent from each other, which means they are not in sync as a group. Eventually, they start changing at different times which is not ideal in terms of user experience. (see why here: JS Event Loop)
The parent component has no information about the status of each contract (expired or not). Therefore, an output in the countdown is necessary to provide the parent such information, so it can take corresponding action (remove/block from list, refresh list, etc).
It’s not the most performant solution since we end up with a bunch of stateful components, each one of them with a timer, each timer performing the same task every second.

Solution #2: Master Timer (One timer to rule them all 🤴💍⚔️)

In order to address the issues from solution #1, we could have moved the logic for calculating the remaining time from the countdown component to the parent component.

The countdown component wouldn’t have any logic anymore, but it would simply display the provided value with some styles. It would now be a stateless component and could be renamed to time-display component.



@Component({
  selector: 'app-time-display',
  template: '<span>{{ time }}</span>',
})
export class TimeDisplayComponent {
  @Input() time: string;
}

In the parent component, we can then use a single setInterval which would iterate over the list of contracts to update the corresponding remaining time, every second. This solves the synchronization issue.



@Component({
  selector: 'app-root',
  template: `
    <div *ngFor="let contract of contracts">
      <span>{{ contract.id }}</span>
      <app-time-display [time]="contract.remainingTime"></app-time-display>
    </div>
  `,
})
export class AppComponent implements OnInit {
  public contracts: Contract[] = MOCK_CONTRACTS;

  ngOnInit(): void {
    setInterval(() => {
      this.contracts.forEach(contract => {
        contract.remainingTime = this.calculateRemainingTime(contract.expiresAt);
      });
    }, 1000);
  }
}

Now the parent component holds information about any contract that expires and can take the corresponding action for such a situation. In our example, we simply block the navigation to the detail of the contract and apply some styles to it.

At this point we solved all the issues from solution #1, but our parent component has more responsibilities now and some imperative code. We could use the power of rxjs to make it more declarative and reduce it’s responsibilities.

Solution #3: RxJS Timer Operator 🚀👨‍🚀

We will be using the rxjs timer operator to transform this into a stream of data and provide it directly to our template with help of the async pipe.

Here the learnrxjs definition of timer operator.

After given duration, emit numbers in sequence every specified duration.

Additionally, we can see in the docs that the operator takes two arguments: initialDelay and period. That means, after initialDelay ms it emits the number 0, and then it emits this value increased by one every period ms. We can call this number the “tick” value and infer the response type as Observable<number>.

We actually won’t be needing this “tick” value, but we use the tick event to make our “remaining time” calculations, like this:



import { Observable, timer } from 'rxjs';

@Component({
  selector: 'app-root',
  template: `
    <div *ngFor="let contract of contracts$ | async">
      <span>{{ contract.id }}</span>
      <app-time-display [time]="contract.remainingTime"></app-time-display>
    </div>
  `,
})
export class AppComponent implements OnInit {
  private contracts: Contract[] = MOCK_CONTRACTS;
  public contracts$: Observable<Contract[]>;

  ngOnInit(): void {
    this.contracts$ = this.countdown();
  }

  private countdown(): Observable<Contract[]> {
    return timer(0, 1000)
      .pipe(
        map(() => {
          this.contracts.forEach(contract => {
            contract.remainingTime = this.calculateRemainingTime(contract.expiresAt);
          });
          return this.contracts;
        }),
      );
  }
}

We use the map operator to both make our calculations and change the return type from Observable<number> to Observable<Contract[]>. We can now encapsulate the countdown function logic in a service to abstract it from the component, make it reusable (we use this feature in several screens) and consume the stream directly into the template.



export class AppComponent implements OnInit {

  private contracts: Contract[] = MOCK_CONTRACTS;

  public contracts$: Observable<Contract[]>;

constructor(private timerService: TimerService) { }

ngOnInit(): void {

    this.contracts$ = this.timerService.countdown(this.contracts);

  }

}

Conclusions

At the end, we achieved the following improvements with our final solution:

Better performance and user experience
Code readability and reusability
It is rxjs friendly (easy integration with ngrx, socket.io, etc)

Acknowledgement

I would like to thank my teammates Kevin and Pablo for implementing these ideas, as well as Nicolás and Pablo Wolff for their feedback.

Demo 🧪

The full code for each solution can be found in the links below. There are extra lines there for clearing the intervals, completing the observable when necessary, and more.

Solution #1: The Countdown Component
Solution #2: Master Timer
Solution #3: RxJS Timer Operator