Foundation Forms - filters

tip

You can click to view our API documentation in a separate area.

A filter is a display that connects to a server resource, such as a Data Server. It enables the user to set one or more fields from the resource to filter information. For example, the user could select trades with a specific broker or trades within a specified value range.

To create a filter, your main tasks are:

• Specify the server resource where the underlying information is coming from.

• Configure the layout using a UI schema (Optional).

tip

In order to display the filtered information, you need to specify another component and synchronise it with the information in the filter.

Filters - basic install

To enable this module in your application, add @genesislcap/foundation-forms as a dependency in your package.json file.

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

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

tip

Whenever you change the dependencies of your project, run the $ npm run bootstrap command again. You can find more information on the package.json basics page.

Register components

Every component that uses filters must register the component in the file where you define its class.

So for example, if I have a component called home, then you need to register the component in the file home.ts.

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

Add a filter*

Below is an example of a foundation-filters using the resourceName attribute. This attribute must be a resource from the server such as dataserver or request server; in this case, we are using a data server called ALL_TRADES.

<foundation-filters resourceName="ALL_TRADES"></foundation-filters>

Configure form using UI schema

You can provide a UISchema to the filter in order to customise which fields should be displayed in the filter forms. The schema.ts file should be in the same folder as the file where you define the class of your route. In the example below, we set only the fields QUANTITY and SIDE.

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

In the template file for your component, you need to import the schema you have created:

import { sampleUISchema } from './schema';
 ...
 export const HomeTemplate = html<Home>`
	...
  <foundation-filters resourceName="ALL_TRADES" :uischema=${() => sampleUISchema}></foundation-filters>
	...
`;

Configure form using JSON schema (optional)

You can configure the information that is retrieved from the server by providing a JSON schema on the client, instead of providing a resourceName. The resourceName gives you all the fields that have been specified in the event on the server. But, with a hard-coded schema, you can change the fields and their order. However, note that if a field changes name or type on the server, you will have to change this in the schema, or it will not work.

The JsonSchema.ts file should be in the same folder as the file where you define the class of your route.

Here is an example of a JsonSchema.ts file that configures the information that is returned by the server:

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

In the template file for the route, you need to import this schema:

import { sampleJsonSchema } from './JsonSchema';
 ...
 export const HomeTemplate = html<Home>`
	...
 	<foundation-filters :jsonSchema=${() => sampleJsonSchema} :uischema=${() => sampleUISchema}></foundation-filters>
	...
`;

Synchronising values with datasource criteria

If you want to synchronise your filter with another display (such as a grid-pro), follow these steps:

1. Register your component in the file where you define the class of your route.

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

2. In the same file, create an @observable variable to store the criteria used in the foundation-filter:

import {... , observable} from '@microsoft/fast-element';
...
export class TEMPLATE extends FASTElement {
...
  @observable allTradesFilters: string
...
}

3. In your template, use the sync function to save the criteria value from the foundation filter into the variable allTradesFilters:

import {sync} from '@genesislcap/foundation-utils';
...
  ...
    <foundation-filters
      resourceName="ALL_USERS"
      :value=${sync((x) => x.allTradesfilters)}>
    </foundation-filters>
  ...
...    

From this point, the criteria used in the foundation-filter are stored in the allTradesFilters variable. You can use this variable with the <grid-pro-genesis-datasource> to match the criteria used in the foundation filter.

4. Assign the allTradesFilters to the criteria attribute of the <grid-pro-genesis-datasource>.:

<zero-grid-pro>
    <grid-pro-genesis-datasource
            resource-name="ALL_TRADES"
            criteria=${(x) => x.allTradesFilters}
    ></grid-pro-genesis-datasource>
</zero-grid-pro>

The outcome is that the foundation-filter displays a form showing all the available fields in the resource. This enables the user to select specific criteria for each field. Beneath this, the zero-grid-pro displays the data filtered by the input criteria.

tip

It is crucial to manipulate the style of the foundation-filter in order to see the zero-grid-pro beneath it.

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