Nuclear Planning Manual

    @trufla/ngx-tru-forms
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.13-rc.2 • Public • Published

    Tru Forms

    Angular 8+ module for generating forms from JSON schema. Refer to documentation for structure of JSON Schema PDF/HTML. This component utilizes Reactive Forms for most of its functionality.

    Table of Contents

    Installation

    npm install @trufla/ngx-tru-forms --save

    Usage

    Module can be used with Angular Material or Bootstrap 4. Import either JsonFormBootstrap4Module or JsonFormMaterialModule or TruUiModule and use it with JsonFormModule. For example:

    Example uses Angular Material

    app.module.ts

    import {
      JsonFormModule,
      JsonFormMaterialModule,
      JsonFormMaterila
    } from '@trufla/ngx-tru-forms';
    // for using tru ui
    // import { JsonFormModule, TruUiModule, JsonFormFieldsService, TruUi } from '@trufla/ngx-tru-forms';
    
    @NgModule({
      imports: [
        JsonFormMaterialModule,
        // for using tru ui
        // TruUiModule
        // for using Bootstrap
        // JsonFormBootstrap4Module
        {
          ngModule: JsonFormModule,
          providers: [
            {
              provide: JsonFormFieldsService,
              useClass: JsonFormMaterial,
              multi: true
            }
            // for using tru ui
            // {
            //   provide: JsonFormFieldsService,
            //   useClass: TruUi,
            //   multi: true
            // }
            // for using bootstrap
            // {
            //   provide: JsonFormBootstrap4,
            //   useClass: TruUi,
            //   multi: true
            // }
          ]
        }
      ]
    })

    app.component.ts

    export class AppComponent {
      schema = {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string",
            "format": "password"
          }
        },
        "required": ["username", "password"]
      };
    
      handleSubmit(e) {
        // e = { username: "john_doe", password: "123456789" }
        this.loginService.login(e);
      }
    }

    app.component.html

    <jf-form
      [schema]="schema"
      [submit]="'Login'"
      (handleSubmit)="handleSubmit($event)"
    ></jf-form>

    Options

    Key Description Required
    [id] Uniquely identify forms if there are multiples on the page
    [schema] JSON Schema object Yes
    [data] JSON Schema default values
    [style] Extra classes and style overrides
    [submit] Text label for submit button
    [cancel] Text label for cancel button
    [outerClass] Wrapper class for the form component
    [submitClass] Class for submit button
    [cancelClass] Class for cancel button
    [isWorking] Toggle form state if using async data process
    [isMultiStep] Treat schema as multi step. See example.
    [viewOnly] Render only the labels and form data. Useful for reports.
    [disabled] Disable all the fields in the form. Set to true for disabled and null otherwise
    [language] Text for translation default is 'en'
    (handleSubmit) Watch for form submission. Return JSON Schema response data
    (handleChange) Watch for form changes
    (handleCancel) Watch for cancel click (emitting value even if form invalid)

    For additional ways to modify and access the form see External Methods.

    Example

    const schema = {
    	"type": "object",
    	"properties": {
    		"first_name": {
    			"type": "string"
    		},
    		"last_name": {
        	"type": "string"
        }
    	},
    	"required": ["first_name"]
    };
    
    const data = {
      "first_name": "Test",
      "last_name": "Me"
    }
    
    const onFormSubmit = (form) => console.log(form);
    <jf-form 
      [schema]="schema" 
      [data]="data"
      (handleChange)="onFormSubmit($event)"
    ></jf-form> 

    Quick Reference

    type: string, number, object, array, boolean
    format (optional): date, photo, textarea
    description (optional): hover text to describe purpose of field
    title: string | array of objects each contains language and value for label or header or array title or object title

    "title": [{"language": "en", "value": "first name"}, {"language": "fr", "value": "le prénom"}]

    enumNames: array of string or array of arrays contains translation array of objects if not provided enum used as default

    // with translation
    "enumNames": [[{"language": "en", "value":  "Yes"}, {"language": "fr", "value":  "Qui"}],
                  [{"language": "en", "value":  "No"}, {"language": "fr", "value": "Non"}]]
    // without translation
    "enumNames": ["Yes", "No"]
    

    verify: Boolean default false duplicate string type for verification
    maxSize: for photo format to verify size, unit are in MB

    Extending

    This module allows for extension via injectors.

    constructor(
      jfDefaultsService: JsonFormDefaultsService,
      jfValidatorsService: JsonFormValidatorsService
    )

    Defaults

    Extend values in default tag.

    this.jfDefaultsService.register('now', () => new Date());

    Validations

    Add JSON validator.

    const ValidatorJSON = (control: AbstractControl) => {
      try {
        JSON.parse(control.value);
        return null;
      } catch (err) {
        return { customError: err.message };
      }
    };
    this.jfValidatorsService.register('field_name', ValidatorJSON);

    field_name has to be valid field including any nesting (as it is display on data and without properties)

    const schema = {
    	"type": "object",
    	"properties": {
    		"first_name": {
    			"type": "string"
    		},
    		"last_name": {
        	"type": "string",
        	"prefix": {
        	  "type": "object",
            "properties": {
              "custom": {
                "type": "string"
              }
            }
        	}
        }
    	},
    	"required": ["make"]
    };

    Fields would be first_name, last_name, last_name.prefix.custom.

    Fields

    Add new field type. Create a component that extends CommonComponent. Add the following as a starting template (or copy from string field).

    import { CommonComponent } from '@trufla/ngx-tru-forms';
    
    @Component({
      template: `
        <label [ngClass]="['jf-label', schema.key, (isRequired() ? 'required' : '')]">
          {{title()}}  
        </label>
        <input
          class="form-control"
          [name]="schema.key"
          [attr.type]="type()"
          [formControl]="control"
          [(colorPicker)]="color"
          [style.background]="color"
          [style.color]="color"
          [style.width]="'40px'"
          (colorPickerChange)="handleColorPickerChange($event)"
        />
      `
    })
    export class CustomComponent extends CommonComponent {
      color: '#0000ff';
    
      handleColorPickerChange(val) {
        this.control.setValue(val);
      }
    }

    Add it to your module:

    entryComponents: [
      ColourPickerComponent
    ]

    Add it via the component:

    [fields]="{'colour': ColourPickerComponent}"

    Also you can disable Submit button by passing

    <jf-form [btnDisabled]="true"></jf-form>

    Now objects of format new_format will show the CustomComponent.

    External Methods

    When referencing the form as a dom element @ViewChild(myForm) myForm, there are certain external functions that can be useful, for example, handling submit of multiple forms manually.

    isValid

    Check if the form is valid.

    submitForm

    Trigger submission of the form. Useful for trigger validation.

    setHeader

    Set header of the form in ngAfterViewInit or after events.

    setFooter

    Set footer of the form in ngAfterViewInit or after events.

    getRequiredFieldCount

    Get number of required fields.

    Styling

    We prefer csswizardry-grids to align and order fields. Form, groups and labels are assigned classes which can be utilized globally or per form. Certain forms fields can be assigned classes on top of current defaults.

    {
      first_name: {
        default: 'one-half grid__item'
      },
      last_name: {
        default: 'one-half grid__item'
      }
    }

    Install

    npm i @trufla/ngx-tru-forms

    DownloadsWeekly Downloads

    105

    Version

    1.1.13-rc.2

    License

    MIT

    Unpacked Size

    2.96 MB

    Total Files

    172

    Last publish

    Collaborators

    • wassimsalib
    • abdelhameed.m
    • trufla-support
    • jvanstaalduine
    • aali-trufla
    • karim60
    • elijah-lucian