Foundation Forms

info

This section contains lots of examples, which you can also explore in our Genesis Community Success repo.

After you have looked at the basics here, you can find more details in our API Docs

foundation-forms is a library for efficiently building complex forms and filters at scale.

At its simplest, a form is a collection of fields for entering data. However, forms can also be very complex, allowing you to add different web components, such as checkboxes, tabbed information or even steps to guide the user through a process. There are also many layout options for the information in the form.

There are two types of schema that enable you to define the layout and content of a form:

• resourceName or jsonSchema defines the underlying data to be shown in the UI (objects, properties, and their types).
• uiSchema defines how this data is rendered as a form, e.g. the order of controls, their visibility, and the layout.

This section gives you examples of how to use them to create forms with different layouts.

Forms - basic installation

info

If you create a Genesis Application using Genesis Create or using command line genx Foundation Forms will already be imported into your project.

If you have not used GenesisCreate or genx to create your project, you need to enable the component:

To do this, follow the steps below.

1. Add @genesislcap/foundation-forms as a dependency in your project. Either run the npm install command or add the package to your package.json file. Whenever you change the dependencies of your project, ensure you run the $ npm run bootstrap command again. You can find more information in the package.json basics page.

npm install --save @genesislcap/foundation-forms

{
  ...
  "dependencies": {
    "@genesislcap/foundation-forms": "latest"
  },
  ...
}

2. Register components

To register the form component, import the Form component in the client/src/components/components.ts file.

import { Form } from '@genesislcap/foundation-forms';
...
Form
...

Adding a form component to the template

To add the <foundation-form> to your template, copy the html snippet below:

<foundation-form
    resourceName="EVENT_TRADE_INSERT">
</foundation-form>

You don't need to create your own schema for the form; this automatically uses the JSON schema generated by the specified endpoint (which you have defined in your back end).

Configuring a form using the UI schema

You can configure the appearance of the form using the UI schema (see below).

Here is an example UI schema for configuring a form:

const sampleUISchema = {
  type: "VerticalLayout",
  elements: [
    {
      type: "Control",
      scope: "#/properties/QUANTITY",
      label: "Quantity",
    },
    {
      type: "Control",
      scope: "#/properties/SIDE",
      label: "Side",
    },
  ],
};

Your template must specify the uischema attribute:

<foundation-form
    resourceName="EVENT_TRADE_INSERT"
    :uischema=${() => sampleUISchema}>
</foundation-form>

Configuring a form using a JSON schema (client-side)

Instead of providing resourceName, you can hard-code the JSON schema on the client.

Here is an example of a JSON schema:

export const sampleJsonSchema = {
  type: 'object',
  properties: {
    SIDE: {
      type: 'string',
      description: 'kotlin.String',
    },
    QUANTITY: {
      type: 'number',
      description: 'kotlin.Double',
    },
    SIMPLE_TRADE_ID: {
      type: 'string',
      description: 'kotlin.String',
    }
  }
};

And we use the same UiSchema as earlier. This creates a form with the same structure as the

<foundation-form
    :jsonSchema=${() => sampleJsonSchema}
    :uischema=${() => sampleUISchema}>
</foundation-form>

info

Use this when you want to avoid fetching metadata from the server, but be aware that it could get out of sync if metadata changes on the server.

Pre-filling a form with data (optional)

The data attribute allows you to pre-fill the form with information. A common use case for this is when editing an existing record.

const existingData = {
  ISSUER_NAME: 'Genesis',
  PRICE: 100,
  MAIN_CONTACT: '555-555-5555',
  PASSWORD: 'secret_password',
};

<foundation-form
    resourceName="EVENT_TRADE_INSERT"
    :uischema=${() => sampleUISchema}
    :data=${() => sampleData}>
</foundation-form>

Handling the submit event

When the Submit button in the form is clicked, the form emits a submit event. You can listen to this in your template by adding @submit="..." to the foundation-form element.

Assuming your class has a method called handleFormSubmit, the second parameter of the callback function ctx.event contains the event emitted by the form element. The event.detail property will contain a payload of the form state that looks like { errors: [...], payload: {...}. Any form errors will be listed in the errors array and the payload property will be an object that matches your jsonSchema.

If you have configured your form with a resource-name property, the form will post the data to the back end event handler specified. You can still listen to the submit event - you might want to clear the form, or show/hide a message etc.

import { customElement, ... } from '@genesislcap/web-core';
...

<foundation-form
    resourceName="EVENT_TRADE_INSERT"
    @submit="${(x, ctx) => x.handleFormSubmit(customEvent(ctx))}"
    :uischema=${() => sampleUISchema}
    :data=${() => sampleData}>
</foundation-form>

Full source code at Forms introduction

License

Note: this project provides front-end dependencies and uses licensed components listed in the next section; thus, licenses for those components are required during development. Contact Genesis Global for more details.

Licensed components

Genesis low-code platform