angular-kladr

angular-kladr

Angular 4+ package for better experience using kladr api service

• Installation
• Setup
• Usage
• Demo

Installation

$ npm install angular-kladr --save

Setup

1. Import KladrModule from node_modules/angular-kladr

import { KladrModule } from 'angular-kladr';

Add imported module to the imports section in NgModule decorator.

@NgModule({
  .
  .
  .
  imports: [
    :
    KladrModule.forRoot({
      isSecure: true
    });
  ]
})

There is an option isSecure for confguring whether to send secure requests (under https protocol) or not.

You can skip adding options. By default, there is an insecure connection configured.

NOTE: forRoot method is required

2. Inject service into your component/service constructor

import { Component } from '@angular/core';
import { KladrService } from 'angular-kladr';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  constructor(
    private kladr$: KladrService
  ){ }
}

Usage

Basic usage

Basically, you need to create collection of type Observable<KladrResponse>.

public cities: Observable<KladrResponse>;

NOTE: KladrResponse type should also be imported from the package

Then create FormControl, which you will get value from in order to pass it into kladr api request.

Assign the request to the collection in the contructor body as shown below:

constructor(private kladr$: KladrService) {
  this.cityControl = new FormControl('');

  this.cities = this.cityControl.valueChanges
    .pipe(
      takeUntil(this.ngUnsubscribe),
      debounceTime(100),
      switchMap(value => {
        const context: KladrSearchContext = {
          ...this.regionContext,
          query: value
        };
        return this.kladr$.api(context);
      })
    );
}
private ngUnsubscribe = new Subject<void>();
private regionContext: KladrSearchContext = {
  limit: 10,
  contentType: KladrContentType.region
};

public cities: Observable<KladrResponse>;
public cityControl: FormControl;

Also, we need to know which city a client will choose to provide some kind of autocomplete

public chosenCity: KladrItem;

chooseCity(city: KladrItem) {
  this.chosenCity = city;
  this.cityControl.setValue(city.name);
}

To make this work let's add some html code in our template:

<div>
  <label for="city">Choose city</label>
  <input type="text" id="city" name="city" [formControl]="cityControl">
  <ul>
    <li *ngFor="let city of (cities | async)?.result">
      <a href="javascript:void(0)" (click)="chooseCity(city)">{{city.name}}</a>
    </li>
  </ul>
  <div>
    <pre>{{chosenCity | json}}</pre>
  </div>
</div>

Combining all together:

1. app.module.ts :

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

import { AppComponent } from './app.component';
import { KladrModule } from 'angular-kladr';
import { ReactiveFormsModule } from '@angular/forms';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    KladrModule,
    ReactiveFormsModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

1. app.component.ts :

import { Component } from '@angular/core';
import { KladrService, KladrResponse, KladrSearchContext, KladrContentType, KladrItem } from 'angular-kladr';
import { Observable, Subject } from 'rxjs';
import { takeUntil, debounceTime, switchMap } from 'rxjs/operators';
import { FormControl } from '@angular/forms';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  constructor(private kladr$: KladrService) {
    this.cityControl = new FormControl('');

    this.cities = this.cityControl.valueChanges
      .pipe(
        takeUntil(this.ngUnsubscribe),
        debounceTime(100),
        switchMap(value => {
          const context: KladrSearchContext = {
            ...this.regionContext,
            query: value
          };
          return this.kladr$.api(context);
        })
      );
  }

  private ngUnsubscribe = new Subject<void>();
  private regionContext: KladrSearchContext = {
    limit: 10,
    contentType: KladrContentType.region
  };

  public cities: Observable<KladrResponse>;
  public cityControl: FormControl;
  public chosenCity: KladrItem;

  chooseCity(city: KladrItem) {
    this.chosenCity = city;
    this.cityControl.setValue(city.name);
  }
}

1. app.component.html :

<div>
  <label for="city">Choose city</label>
  <input type="text" id="city" name="city" [formControl]="cityControl">
  <ul>
    <li *ngFor="let city of (cities | async)?.result">
      <a href="javascript:void(0)" (click)="chooseCity(city)">{{city.name}}</a>
    </li>
  </ul>
  <div>
    <pre>{{chosenCity | json}}</pre>
  </div>
</div>

Demo

The demo will be available soon.

Changelog

0.1.2 (2019-04-21)

<a name="0.1.1"></a>