# 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.

#### How form-input-monetary works

When you use `form-input-monetary` with a `field_name`, the component automatically creates **two fields**:

| Field                | Description                  | Example   |
| -------------------- | ---------------------------- | --------- |
| `{field_name}`       | Value in cents (sent to API) | `120034`  |
| `{field_name}_human` | User-friendly display value  | `1200.34` |

For example, if you configure:

```json
{
  "type": "form-input-monetary",
  "config": {
    "field_name": "data.item_value"
  }
}
```

When the user types `1200.34`:

* `input.data.item_value` = `120034` (cents, sent to API)
* `input.data.item_value_human` = `"1200.34"` (display value)

The `_human` field is useful for displaying the value back to users in summary screens or content strings.

### 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](https://en.wikipedia.org/wiki/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:

```json
{
  "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:

```json
{
  "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:

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