ngx-data-driven-forms

A framework for quickly generating web forms from just a simple JSON object.

Installation

Installation is simple and can be done through Node Package Manager. The library is divided into two major sectors:

• Core Module (DDFormsCoreModule)
• Defaults Module (DDFormsDefaultsModule) [has further subdivisions]

To install just run

npm install @nys-hcr-its/ngx-data-driven-forms

This will install the library and its only non-angular dependency (ngx-markdown, used for some text rendering in the Defaults Module).

Basic Setup

The basic framework of this library is provided entirely by the Core Module. This provides the structure and render functions for the library.

All you have to do is import the Core Module in your Base App Module.

Note: Only importing the Core Module will require you to define default renderers.

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

Including Defaults

In order to get stuff to appear on the page, renderers need to be registered with the libray.

The libary provides an opt-in Module that automatically registers some basic functionality and views. In order to use this library, you will also have import ngx-markdown which is used for text rendering.

Again just import these two modules into your Base App Module.

@NgModule({
  declarations: [
  ],
  imports: [
    BrowserModule,
    ReactiveFormsModule,
    DDFormsCoreModule,
    DDFormsDefaultsModule,
    MarkdownModule.forRoot(),
  ],
  providers: [],
  bootstrap: []
})
export class AppModule { }

This will cause all default renderers to be registered with the library, and allow text to be rendered.

However, in order to fully take advantage of ngx-markdown you will also have to add node_modules/marked/marked.min.js to your app scripts in the angular.json file.

Further plugins, functionality and configuration can be added by following the info at https://www.npmjs.com/package/ngx-markdown#installation

It is recommended that you import these modules in either the module that is using the ddforms library or in a shared library. Importing and using it in a different location can cause race conditions.

Basic Usage

To use data driven forms you have to either start the render engine yourself or use one of our provided entry points.

The entry points are normal Angular components that handle entering the render engine NOTE: They do not manage state! You must handle state yourself.

For the purpose of this documentation we will be using the application entrypoint, which is likely the most common entrypoint you will use.

<ddforms-application-container
  [application]={an application object}
  [control]={a form control in an expected layout}
  [currentPageIndex]={the target page to be shown (you keep track of this)}
>
</ddforms-application-container>

The entrypoint expects three(3) inputs; application, control, and currentPageIndex. These three inputs will be used to render the application using the render engine.

application is an instance of our Application class, which holds your form config and some methods for utility.

  application = new Application({...<your form config here>})

control is an Angular ReactiveForms Form that handles all of our databinding and validation for us. The render engine expects a specific structure which is generated by our handy FormGenerationService

  control = this.formGenerator.buildApplicationControl(<initial value or null>, <an application object>);

currentPageIndex is a number that represents the current page of the application. This is used to determine which page to render. You will have to keep track of this value yourself and update it when the user navigates to a new page.

Styling

Our library is designed to be as unopinionated as possible. This means that by default, it will not provide any styling for you. However, we do provide some basic scss files that you can use to get started. In addition to this, we also provide a few classes that you can use to style your forms. These classes also follow bootstrap conventions, which will allow you to use bootstrap styling if you wish.

To use or basic styles, you can include the following in your angular.json file.

"styles": [
  "node_modules/@nys-hcr-its/ngx-data-driven-forms/styles/default-styles.scss"
],

Further documentation will be available soon. For now, please refer to the demo application for examples of how to use the library.