Schema-form-designer NPM

MSI JSON Form Widget Library

Quick Start: NPM Installation

The .npmrc file used for @msi/cobalt will also authorize you to install this package.

npm install @msi/json-forms

Json-forms '@msi/json-forms@11.4.0-beta-1' is upgraded to consume new cache library @msi/codetable-cache": "^1.0.0-beta-7

(https://dev.azure.com/msi-cie/OneRMS/_git/LSM-Code-Tables?path=/src/msi/codetable-cache/package.json) @msi/json-forms@11.4.0-beta-1 version includes followings changes: 1. Added dependency for msi-codetable-cache 2. Replaced lsm calls with msi-codetable-cache 3. Replaced formula calls with resolution from msi-codetable-cache 4. Replaced document definition creation with factory method 5. Removed unused code a. loaders / isLoading indicators b. unused wizard components c. unused token/policy/cache classes

For using json-forms library @msi/json-forms@11.4.0-beta-1 in your application you need to take following actions: 1. Install beta version of cache @msi/codetable-cache@1.0.0-beta-7. 2. Install @msi/json-forms@11.4.0-beta-1. 3. Import CodetableCacheModule in the app module of your application. 4. Initialize code table cache by calling await cacheService.init(userInfo). 5. Replace 'definitionService.initCache' calls with 'await definitionService.init(userInfo)'. 6. Remove references for LoaderService. 7. Reference different methods available in code table cache library as required. https://dev.azure.com/msi-cie/OneRMS/_git/LSM-Code-Tables?path=/src/msi/codetable-cache/src/lib/services/cache-service/cache.service.ts

Demo Site

Hosted

Daily builds deploy to https://formsbuilder.dev.commandcentral.com

Local

npm start

Add to your host file: 127.0.0.1 formsbuilder.local.commandcentral.com Navigate to https://formsbuilder.local.commandcentral.com.

The app will automatically reload if you change + save any of the source files.

Local + Local API

If the development API is down (i.e. no documents appear in main designer dropdown), try a hard browser refresh. If dropdown still empty follow steps below to run API locally.

Start Forms Engine API

Clone repo json-forms-config-api
Open FormsEngine-DocConfig.sln in Visual Studio (for reference see launchSettings.json)
F5 Run the project (keep IIS Express launched Chrome window open)

Start Form Designer (which calls the API)

In repo schema-form-designer
Open file environment.ts
Set docConfigApi: 'https://localhost:44346'
npm start

Usage

Hosting Angular Application

Refer to the demo application (in /src) for an example of usage.

Step 1: Add Typescript import to your root app module (e.g. app.module.ts)

import {
  FORMSENGINE_APP_CONFIG_TOKEN,
  MsiCobaltFrameworkModule,
} from "@msi/json-forms";

Step 2: In the same file, also import the module in your Angular @NgModule declaration

@NgModule({
  declarations: [...],
  imports: [
    MsiCobaltFrameworkModule,
    LoggerModule.forRoot({ level: environment.logLevel }),
    NgxMaskModule.forRoot()
  ],
  ...
})

Step 3:

You are now ready to begin using for components in your Angular application. You can use them in HTML templates in your angular app, for example:

<msi-json-form-viewer
  [(document)]="documentData"
  (change)="changed($event)"
  (submit)="submitted($event)">
</msi-json-form-viewer>

Step 4:

Custom validation events such as disabling of Save button can be accomplished by observing validationErrors in msi-json-form-viewer (doc-viewer.component.ts)

@Output() validationErrors = new EventEmitter<any>();

Refer to the example JSON schema and layout snippets in the Hosted Form Desinger and its sourcecode (in /src) for code snippets and examples of usage.

Development

Remember to update demos, tests, and this file if making changes!

1. Development server

npm start

Navigate to https://formsbuilder.local.commandcentral.com.

The app will automatically reload if you change any of the source files.

2. Build component library

npm run build-lib

Output goes to /dist/msi/json-forms.

3. Apply UBS styles

asdfasdfas - document!

@import './msi/json-forms/assets/styles/_cobalt_responsive.scss';

Records applications use Cobalt, plus a few overrides. Import this style sheet to match UBS designs.

Localization

Preparing project to translate forms text using Transloco library

Step 1: Install Transloco as stated here https://ngneat.github.io/transloco/docs/installation/ run

ng add @ngneat/transloco

Transloco creates boilerplate files for the requested translations, including transloco-root.module.ts and config file

Step 2: Example transloco-root.module for English and Canadian French

@NgModule({
  exports: [ TranslocoModule ],
  providers: [
    {
      provide: TRANSLOCO_CONFIG,
      useValue: translocoConfig({
        availableLangs: ['en-US', 'fr-CA'],
        defaultLang: 'en-US',
        // Remove this option if your application doesn't support changing language in runtime.
        reRenderOnLangChange: true,
        prodMode: environment.production,
      })
    },
    { provide: TRANSLOCO_LOADER, useClass: TranslocoHttpLoader }
  ]
})

Corresponding transloco.config.js for above

module.exports = {
  rootTranslationsPath: 'src/assets/i18n/',
  langs: ['en-US', 'fr-CA'],
  keysManager: {}
};

Project should now be able to translate if given translations in the assets folder

Uprgrading forms with localization

Step 1: Make sure all of the forms titles and text that need to be translated are in the layout and not in the schema

Step 2: Create a key for each title/text. The standard is creating a unique path to the form and using camelcase Example

formsEngine.lawIncident.addNote

This would be in Forms Engine, is in the law-incident form, and is the title for the "Add Note" text

Step 3: Replace title/text in layout with key

Step 4: In project where form will be used add key and the translated value in the proper language file located in 'src/assets/i18n/forms-engine/{{lang}}.json'

Uprgrading forms without localization

Do Step 1 from "Preparing project to use forms with localization".

After running ng add @ngneat/transloco, with "en" and "N" for questions it asks, it should have created transloco.config.js and transloco-root.module.ts and added TranslocoRootModule` to your app's app.module.ts file.

If running this command fails, you can create them manually and find example files here

If it doesn't display labels on the form, check the error message in the browser console and add a folder and/or move the en.json file accordingly. The error message will show the path it's expecting the translation file to be in.

To not have console warnings on missing translation, add

missingHandler: {
  allowEmpty: true,
  logMissingKey: false
},

to translocoConfig inside transloco-root.module.ts

e.g.

{
  provide: TRANSLOCO_CONFIG,
  useValue: translocoConfig({
    availableLangs: SUPPORTED_LANGS,
    defaultLang: DEFAULT_LANG,
    fallbackLang: DEFAULT_LANG,
    // Remove this option if your application doesn't support changing language in runtime.
    reRenderOnLangChange: true,
    missingHandler: {
      allowEmpty: true,
      logMissingKey: false
    },
    prodMode: environment.production,
  })
}

You don't have to add anything to the translation file and your form should display as usual.

Digital Evidence

Built from the Tiles Container widget. Currently only supports the law-incident form page and implementation can be seen in the law-incident-form-page.component.ts located in the OneRMS-CRV-UI repo

Refresh Digital Evidence

To refresh files for digital evidence the refreshDigitalEvidence from the definition.service.ts must be called with the case number of the law incident in the following format

{ caseNumber: 'case number' }

Styles

Component styles are based on a 12-column Bootstrap style Grid, using the same CSS Flex percentages as Bootstrap 4.

Layout item

{
  "type": "flex",
  "flex-flow": "row wrap",
  "items": [
    {
      "key": "person.firstName",
      "flex-grid": "2"
    }
  ]
}

A flex-grid value of "2" is Bootstrap eqiuvalent of a "col-2". Optionally give a grid basis if not using the default of 12. For instance if your main view is a 3 (sidenav) / 9 (content) split, and all items are in the 9-column right side of the screen, use a 9-column grid basis.

"flex-grid": "2 9",

View Mode

Ability to render in "view" mode was added fall 2021. Add the following node to your data JSON, and forms engine will render all viewable controls in a read/print mode (i.e. input boxes rendered as pure text, array trash icons removed, etc.)

Important Note: If the "view" state attribute was previously saved to your data document in Cosmos, and your form is loaded into Forms Builder, the Layout JSON will appear as already transformed (i.e. "subType" attributes have appeared).

  // Data
  "meta": {
    "state": "view"
  },

Behind the scenes

  // Layout
  {
    "key": "firstName",
    "type": "input"
  },

is changed to

  {
    "key": "firstName",
    "type": "view",
    "subType": "input"
  },

Note, because engine allows "type" to be omitted from layout, if type is missing the code falls back to the schema. For example, below schema type of "string" would be read, and layout item type of "input" assumed

  // Schema Fallback
  "firstName": {
    "type": "string"
  },

is interpreted as layout type "input" and converted to

  // Layout
  {
    "key": "firstName",
    "type": "view",
    "subType": "input"
  },

Versioning

X.Y.Z e.g. 1.1.2

Where:

X - Changes that break backward compatibility (Tied to angular/cobalt Major)
Y - Backward compatible new feature
Z - Backward compatible bug fix

You can specify which kinds of updates your application can accept in the package.json file.

If you were starting with a package 1.0.1, this is how you would specify the ranges:

Patch releases: 1.0 or 1.0.x or ~1.0.4
Minor releases: 1 or 1.x or ^1.0.4
Major releases: * or x

Publication

NPM Feed Registry

Azure Feed for common-ui

Bugs

Coming Soon

Support

If you need support from the P1 Team, feel free to contact us using one of following channels:

through email avengers@motorolasolutions.com
directly on Forms Engine Integration google chat

Copyright

@infinitebrahmanuniverse/nolb-sch @everything-registry/sub-chunk-2715

12.0.0-beta.1

2 years ago

schema-form-designer v12.0.0-beta.1