@siren-js/ng

Library for working with Siren in Angular, primarily building dynamic forms backed by Siren actions.

Installation

Install this package (and its peer dependency) in your Angular app from NPM.

npm install @siren-js/ng @siren-js/core

You will likely also want to install the Siren.js client for submitting Actions.

npm install @siren-js/client

Dynamic Forms

The actionToFormGroup() and fieldToFormControl() utility functions allow for easily building dynamic forms from Actions and Fields from @siren-js/core.

From Action to FormGroup

The actionToFormGroup() function accepts an Action object and builds a FormGroup with a control for each field in the Action's fields using the fieldToFormControl() function. The FormGroup's controls are indexed by the Field's name.

Here's an example component that uses the actionToFormGroup() component. For a more complete example, see the example project.

@Component(/* ... */)
export class MyDynamicFormComponent implements OnInit {
  @Input() action!: Action;
  formGroup!: FormGroup;

  get fields(): Field[] {
    return action.fields ?? [];
  }

  ngOnInit(): void {
    this.formGroup = actionToFormGroup(action);
  }
}

<form [formGroup]="formGroup">
  <div *ngFor="let field of fields">
    <!-- display fields, binding to FormControls -->
  </div>
</form>

From Field to FormControl

The fieldToFormControl() function builds a FormControl from a Field object. This function offers more fine-grained control over building dynamic forms.

The generated FormControl will keep the Field's value (with a few exceptions mentioned below) in sync with the FormControl's value via the valueChanges Observable.

<div [formGroup]="formGroup">
  <input [type]="field.type" [formControlName]="field.name" />
</div>

Checkbox Controls

In Angular's reactive forms, the value of a FormControl must be true or false, indicating its checkedness. Therefore a FormControl generated from a checkbox Field updates the Field's checked property, rather than its value.

If the checkbox Field is required, then a ValidatorFn is added to the FormControl to ensure the checkbox is checked. Additionally, if the Field is disabled, then the FormControl is also disabled.

Radio Button and Select Controls

When binding FormControls to radio buttons or dropdowns, be sure to set the input element's value to the index of the corresponding group or options item.

<div [formGroup]="formGroup">
  <label *ngFor="let button of buttons; index as i">
    <input type="radio" [value]="i" [formControlName]="field.name" />
  </label>
</div>

File Upload Controls

Due to limitations with Angular's reactive forms, the FormControl generated from a file Field cannot properly stay in sync for action submission. For that, we provide the SyncFilesDirective, which updates a Field's files property when the corresponding file upload input element's selected files changes.

To utilize this directive, start by importing the SireNgModule in your app:

import { SireNgModule } from "@siren-js/ng";

@NgModule({
  imports: [SireNgModule /* ... */],
  // ...
})
export class AppModule {}

Then bind sireNgSyncFiles to the corresponding Field on your file upload input element:

<div [formGroup]="formGroup">
  <input type="file" [sireNgSyncFiles]="field" />
</div>