Rules For Robust Application

Rules For A Robust Application

In order for an application to be future proof, there are some basic rules that should be followed.

1. Use value-as-cents for monetary values

Lets say that a customer is trying to insure his digital camera. One of the pieces of information that must be collected is the value of the camera.

The customer knows the value of this item in EUR. In the KASKO platform monetary values are used as cents.

This means that if the customer types in 1200.34 EUR, it must be converted to 120034 when sent to the KASKO API.

For this to happen automatically, form-input-monetary component can be used.

2. Field names must follow common convention

1. Field names must be lowercased;

2. Field names must use underscores;

3. Some field names are not acceptable (see table below);

Examples:

Good:
item_value
item_name

Bad:
itemValue
Item_name
Item_Name

Wrong field names:

Field Name	Correction
postal_code	postcode
postalcode	postcode
zip_code	postcode
zip	postcode
surname	last_name

3. Dates & Times

Datetime values MUST always be in UTC. Storing times in UTC has HUGE advantages compared to storing them in local timezone.

When API needs to accept a date/time value, it must always accept the date/time values formatted as ISO 8601 string. iso_date validation rule can be used for this.

When using date input components in the frontend (i.e. form-datepicker), the custom input is automatically converted to an ISO 8601 date if iso_date validation rule has been set.

4. Percentages

When dealing with percentages, use decimal values. For example, if you need to store 15%, then you should store it as decimal 0.15.

Rules For Defining Components

There are some rules to follow when creating a new component either custom one or internal framework component.

1. Fields

When there's need to use a name for some input field, config property name for it must be either field_name or should end with _field_name. And this should be in root of component config. This way framework and webapp builder know what to track.

Note: Component can have multiple fields defined this way at the same time.

Examples:

Good:
field_name
custom_field_name

Bad:
fieldName
Field_Name
field
name

Full good example of component definition:

{
  "type": "my-component",
  "config": {
    "field_name": "first_name"
  }
}

2. Contents

Using content keys is a crutial way to get translated text into component. For this we use content keys. These must always be defined in component config with property name content_key or should end with _content_key. Values for these properties can be string or Record<string, string>. This way our content extraction scripts and webapp builder know what keys are used.

Examples:

Good:
"content_key": "form.first_name.label"
"content_key": {"label": "form.first_name.label"}
"custom_content_key": "form.first_name.label"
"custom_content_key": {"label": "form.first_name.label"}

Bad:
"content": "form.first_name.label"
"content_keys": {"label": "form.first_name.label"}
"contentKey": "form.first_name.label"
"key": "form.first_name.label"

Full good example of component definition:

{
  "type": "my-component",
  "config": {
    "content_key": "form.first_name.label"
  }
}

3. Child Components

Components can contain child components and must be defined in root of component config in property named components or ending with _components. This way framework and webapp builder know how to handle child components.

Note: For custom webapp components that contain child components with e.g. header_components name, slot name for it will be header.

Examples:

Good:
components
header_components
footer_components

Bad:
component
components_list
columns

Full good example of component definition:

{
  "type": "my-component-one",
  "config": {
    "content_key": "form.first_name.label",
    "components": [
      {
        "type": "my-component-two"
      }
    ]
  }
}