# Field types

When you define a field with only a string as the name of the field Kontrl will have to **guess** what the type of your fields are. Even though we are very good at guessing here at Kontrl we will still be wrong from time to time.

Kontrl **Field Types** to the resque. Fields types tell Kontrl how a field should be showed and edited in the application. Let's look at an example.

```js
kontrl.table({

  // Other settings

  fields: [
    // Defines a field with the type "string"
    kontrl.field("first_name", kontrl.types.string()),
    // Defines a field with the type "email"
    kontrl.field("email", kontrl.types.email()),
    // defines a field with the type "boolean"
    kontrl.field("is_subscribed", kontrl.types.boolean())
  ]
});
```

**Supported fields:**

- [string](#field-type-string)
- [uuid](#field-type-uuid)
- [int](#field-type-int)
- [email](#field-type-string)
- [boolean](#field-type-boolean)
- [date](#field-type-date)
- [time](#field-type-time)
- [datetime](#field-type-datetime)
- [created_at](#field-type-created_at)
- [updated_at](#field-type-updated_at)
- [text](#field-type-text)
- [image](#field-type-image)
- [wysiwyg](#field-type-wysiwyg)
- [custom](#field-type-custom)

## Created at & Updated at

If your table needs generated created at & updated at fields then there is a **shortcut**.

```js
kontrl.table({

  // Other settings

  fields: [
    "first_name",
    "last_name",
    // This will automatically generate "created_at" and "updated_at" fields.
    ...kontrl.timestamps() 
  ]
});
```

It's also possible that your timestamps **have different names**. In that case you can offer these names as parameters to the timestamps function.

```js
function timestamps(createdAtName = "created_at", updatedAtName = "updated_at") { ... }
```

**For example:**

```js
kontrl.table({

  // Other settings

  fields: [
    "first_name",
    "last_name",
    // You can name the timestamp columns anything you want.
    ...kontrl.timestamps("inserted_at", "changed_at") 
  ]
});
```

## Field settings

When you define a field, you can also give it some custom settings. The currently defined field settings are:

- **hidden** Can the user see this field? (defaults to *FALSE*)
- **editable** Can the user edit this fields? (default to *TRUE*)
- **required** Is this field required when editing or creating? (defaults to *FALSE*)

**For example:**

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("email", { required: true }),
    kontrl.field("password", { hidden: true, editable: false })
  ]
});
```

## Field type String

The field data are simple strings with no extra information. These will be represented by a HTML input type text.

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("first_name", kontrl.types.string())
  ]
});
```

## Field type UUID

The UUID field represents a UUID as by [RFC 4122](https://tools.ietf.org/html/rfc4122).
By default it **auto generates** the value.

```js
kontrl.table({

  // OTher settings

  fields: [
    kontrl.field("my_uuid", kontrl.types.uuid())
  ]
});
```

### Important

If you'd like to use a uuid as an identifier make sure to make it editable.

```js
kontrl.table({

  // OTher settings

  identifier: ["uuid"],

  fields: [
    kontrl.field("uuid", kontrl.types.uuid())
  ]
});
```

**By default, uuid version 4** is used.
The uuid() function can take a function stating the version.
Version **4** and version **1** are **supported**.

```js
kontrl.table({

  // OTher settings

  identifier: ["uuid"],

  fields: [
    kontrl.field("uuid", kontrl.types.uuid({ version: 1 }))
  ]
});
```

### I'll make my own UUID

If you don't need us to generate your UUID, you can set **autoGenerate** to false.

```js
kontrl.table({

  // OTher settings

  fields: [
    kontrl.field("uuid", kontrl.types.uuid({ autoGenerate: false }))
  ]
});
```

## Field type Int

The int field can only contain whole numbers (both positive and negative).
When using the dashboard on mobile the numeric keyboard will be shown.

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("age", kontrl.types.int())
  ]
});
```

## Field type Email

The data from this field is an email address and will have some simple validation to make sure that is true.
The data will also be made lowercase before being saved to the database.

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("email", kontrl.types.email())
  ]
});
```

## Field type Boolean

A boolean, true or false. The allowed inputs are:

- true / false
- "true" / "false"
- 0 / 1

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("is_admin", kontrl.types.boolean())
  ]
});
```

## Field type Date

A date. We suggest first looking over the global application settings to know how Kontrl handles timezones and date formats. If timezones are of no importance to you and you're using ISO then you can just use the date type without any additional settings.

supported formats are:

- ISO (by default)
- SQL Date

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("last_online", kontrl.types.date())
  ]
});
```

The date type can also take an object as a parameter to set settings specifically for that date field.

Supported settings:

- **dateNotation**

To find out what these settings mean and how they work check out the global settings page.

For example:

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("last_online", kontrl.types.date({ dateNotation: "detect" }))
  ]
});
```

## Field type Time

A Time. We suggest first looking over the global application settings to know how Kontrl handles timezones and clock settings. If timezones are of no importance to you and you're using the 24h clock notation (without AM/PM) then you can just use the time type without any additional settings.

The time type can also take an object as a parameter to set settings specifically for that time field.

Supported settings:

- **useUserTimezone**
- **dateTimezone**

To find out what these settings mean and how they work check out the global settings page.

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("meeting_at", kontrl.types.date({ dateNotation: "detect" }))
  ]
});
```


## Field type DateTime

A datetime field containing both date and time information. We suggest first looking over the global application settings to know how Kontrl handles timezones and date formats. If timezones are of no importance to you and you're using ISO then you can just use the date type without any additional settings.

supported formats are:

- ISO (by default)
- SQL Date
- Timestamp in seconds
- Timestamp in milliseconds

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("last_online", kontrl.types.datetime())
  ]
});
```

The datetime type can also take an object as a parameter to set settings specifically for that datetime field.

Supported settings:

- **useUserTimezone**
- **dateTimezone**
- **dateNotation**
- **clockSize**
- **dataTimezone**
- **originFormat**


To find out what these settings mean and how they work check out the global settings page.

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("meeting_at", kontrl.types.datetime({ clockSize: "24h" }))
  ]
});
```

## Field type Text

This field is used for text for which a normal textbox is not big enough. This will be represented by a HTML textarea.

This component does not have any wysiwyg functionality. If you need that kind of functionality we suggest creating a custom type editor (see custom type editor section).

The reason we don't currently provide a wysiwyg editor is because we don't know what your data looks like.

## Field type Image

Takes a URL and shows it as an image.

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("avatar_image", kontrl.types.image())
  ]
});
```

It's also possible to add a baseURL in case the data from this field are relative paths.

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("avatar_image", kontrl.types.image({ baseUrl: "http://freepics.com/" }))
  ]
});
```

## Field type CreatedAt

This field will automatically generate a timestamp for the given field when data gets created for this table.

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("inserted_at", kontrl.types.created_at())
  ]
});
```

## Field type UpdatedAt

This field wil automatically generate a timestamp for the given field when data gets created or updated for the given table.

```js
kontrl.table({

  // Other settings

  fields: [
    kontrl.field("updated_at", kontrl.types.updated_at())
  ]
});
```

## Field type WYSIWYG

**QuillJS** is included in the project as a WYSIWYG editor.
Currently it only **supports HTML** as output and input although more formates are being worked on.

```js
kontrl.table({
  
  // Other settings

  fields: [
    kontrl.field("blog_text", kontrl.types.wysiwyg())
  ]
})
```

You can choose change the toolbar to include all default QuillJS functionality.
<a href="https://quilljs.com/docs/modules/toolbar/" target="_blank">More info in the QuillJS documentation</a>

```js
kontrl.table({
  
  // Other settings

  fields: [
    kontrl.field("blog_text", kontrl.types.wysiwyg([
      { header: 1 },
      { header: 2 },
      "bold",
      "italic"
    ]))
  ]
})
```

## Field type custom

You can add your own custom field types.

A field type defines a few things:

- **name** the name of the field. This must not collide with any other existing fields (even the predefined fields)
- **category** gives Kontrl some basic information about how the field is saved (defaults to string)
- **beforeSave** a function that gets run before the value gets saved ()
- **beforeCreate** a function that gets run before the value gets created the first time
- **defaultValue** the value that will be used when showing the create form
- **collectionTemplate** what it looks like in a table (defaults to a string textbox)
- **editTemplate** what it looks like  (defaults to a string textbox)

All of these are **optional except for name and category**

```js
// make a simple field that works exactly like the string field
const customType = kontrl.customType({
  name: "password"
});

// We can then use it in a table
kontrl.table({

  // Other settings
  
  fields: [
    kontrl.field("password", customType)
  ]
})
```

We can use beforeSave to set the value before it is saved

```js
const customType = kontrl.customType({
  name: "password",
  beforeSave(value) {
    return my_encrypt_function(value)
  }
})
```

The same can be done with beforeCreate

```js
const customType = kontrl.customType({
  name: "password",
  beforeSave(value) {
    return my_encrypt_function(value);
  },
  beforeCreate(value) {
    return my_encrypt_function(value);
  }
})
```

You can also provide a default value for the "create new" form

```js
const customType = kontrl.customType({
  name: "password",
  beforeSave(value) {
    return my_encrypt_function(value);
  },
  beforeCreate(value) {
    return my_encrypt_function(value);
  },
  defaultValue() {
    return my_generate_random_string_function();
  }
})
```

### collectionTemplate

The collectionTemplate defines how the field is shown in the table.

You can use a **custom template** as a collectionTemplate.

```js
const customType = kontrl.customType({

  // Other settings

  collectionTemplate: {
    custom_component: `{ template: "<div>****</div>" }`
  }
})
```

This component can take the following props:

- **data** the value of the field in your database
- **meta** value you can provide yourself

It's possible to provide meta data

```js
const customType = kontrl.customType({

  // Other settings

  collectionTemplate: {
    custom_component: `{ props: ['meta'], template: "<div>{{ this.meta.my_text }}</div>" }`,
    meta: {
      my_text: "Some text"
    }
  }
})
```

### editTemplate

editTemplates define what the field should look like when editing and when creating.

You can provide a custom component as an editTemplate.

```js
const customType = kontrl.customType({

  // Other settings

  editTemplate: {
    custom_component: `{ template: '<input type="text" placeholder="Password" />' }`
  }
})
```

This component can take the following props:

- **value** (when editing) the value of the field in your database
- **meta** value you can provide yourself
- **disabled** a boolean depending on the field disabled setting, false by default.
- **error** null by default, when an error is thrown for that field, this will be a string

It's possible to provide meta data

```js
const customType = kontrl.customType({

  // Other settings

  editTempalte: {
    custom_component: `{ template: '<input type="text" placeholder="Password" />' }`
    meta: {
      my_text: "Some text"
    }
  }
})
```