Nerdy Programmers Mingling

    @siren-js/ng
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.1 • Public • Published

    @siren-js/ng

    Node Package Build Status Code Coverage License Contributing

    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>

    Install

    npm i @siren-js/ng

    DownloadsWeekly Downloads

    1

    Version

    0.1.1

    License

    MIT

    Unpacked Size

    114 kB

    Total Files

    21

    Last publish

    Collaborators

    • dillonredding