Starter Apps/Templates
Angular Starter
State Management
Api Store Creator
UI Store Creator
Store Communication
RXJS Operators
CacheMap
SmartDistinctUntilChanged
Components

Forms

Form Fields
Form Generator
Mapping/GIS
Services
Storage
DOM
SignalR
Service Worker
Utilities
Script Loader
Lib Loader
FormGroup 2 Api
Remove Nils
Image Resizer
Focus Trap
Dialog
Schematics
Generators
PWA Generation
Assets
Root Assets
Author: Jerrol Krause

FormGroup 2 Api

Manage relationships between a form group mega model and a REST endpoint. When this method is called, it will automatically determine which models in the form group need to be saved and where to save them. Supports POST/PUT/PATCH/DELETE.

Imagine that you have a formgroup with the following structure:

        
  {
    loanApplication: {
      borrowers: [
        {
          address: {},
          incomes: [{}],
          assets: [{}],
          liabilities: [{}]
        }
      ]
    }
  }

And then a REST api with full CRUD operations for each model similar to the following:

/api/v1/loanApplications
/api/v1/borrowers
/api/v1/address
/api/v1/incomes
/api/v1/assets
/api/v1/liabilities

In a large non-linear form figuring out what data has changed and where it needs to go is a huge task. By defining the relationship between the form group and the api we can automate all this interaction.

Key Features

  • Recursive: Supports complex deeply nested form models. Is smart enough to dig through arrays in objects in arrays etc
  • All CRUD operations supported: The utility will check the dirty flag to see if any data in the model has changed. If so, it will check if a uniqueID has already been set. If yes, a PUT/PATCH will be performed, if no it will be POST. To perform a delete, set of property of '$$deleted' to true before the utility runs.
  • Handle API responses automatically: Responses from the api are patched into the existing model (useful for things like adding in the uniqueID on POST) and the model will be removed from the form group on a successful DELETE.
  • Resets automatically: After a successfull api call, all models that have been modified have have their dirty flags reset to reset up for future saves
  • HTTP requests run in parallel: All changed models have their http calls run in parallel as a single subscription
  • Supports changed props only By default it will only send the deltas of any changed models

1. Create the form group

For larger models that start as JSON it's convenient to use the jsonToFormGroup utility function found in @ntersol/forms. Otherwise just use form builder. 

                
// Import util from forms library
import { jsonToFormGroup } from '@ntersol/forms';

// Generate form group from JSON input
public formGroup = jsonToFormGroup({
  loanApplication: {
    borrowers: [
      {
        address: {},
        incomes: [{}],
        assets: [{}],
        liabilities: [{}]
      }
    ]
  }
})

// Alternative you can create it the hard way using form builder:
// Import form builder
import { FormBuilder } from '@angular/forms';

// Inject into constructor
constructor(private fb: FormBuilder) {}

// Create form group
public formGroup = this.fb.group({
  loanApplication: this.fb.group({
    borrowers: this.fb.array({
      ...
    })
  })
})

2. Setup

Import the FormGroup2ApiModel interface and use that to create the model that the "saveFormGroup" function will use 

                
// Import interface
import { FormGroup2ApiModel } from '@ntersol/utils';

// Prepend slug for api url
const apiBase = environment.endpoints.apiUrl;

// Main model
export const formGroupModel: FormGroup2ApiModel[] = [
  {
    path: 'loanApplication',
    uniqueID: 'guid',
    ignoreProps: ['borrowers', 'property'],
    apiUrl: apiBase + '/loanapplications',
  },
  {
    path: 'loanApplication.borrowers',
    uniqueID: 'guid',
    parent: {
      uniqueID: 'guid',
      parentID: 'loanApplicationGUID',
    },
    apiUrl: (parent: any) => apiBase + '/loanapplications/' + parent[0]?.loanApplicationGUID + '/borrowers',
    apiUrls: {
      patch: apiBase + '/borrowers',
    },
    ignoreProps: [
      'assets',
      'address',
      'liabilities',
      'incomes',
    ],
  },
  {
    path: 'loanApplication.borrowers.assets',
    uniqueID: 'guid',
    parent: {
      uniqueID: 'guid',
      parentID: 'borrowerGUID',
    },
    apiUrls: {
      patch: apiBase + '/assets',
      delete: apiBase + '/assets',
    },
    apiUrl: (parent: any) => apiBase + '/borrowers/' + parent.guid + '/assets',
  },
];

3. Perform Save

Import the "saveFormGroup" function, supply the angular http service, the formGroupModel that was just created above and then the form group. 

                
// Import save method
import { saveFormGroup$ } from '@ntersol/utils';

// Perform save
saveFormGroup$(this.http, formGroupModel, formGroup).subscribe(() => {
  // Do something when all api calls complete successfully
})