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.

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
uuid
int
email
boolean
date
time
datetime
created_at
updated_at
text
image
wysiwyg
custom

Created at & Updated at¶

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

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.

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

For example:

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:

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.

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. By default it auto generates the value.

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.

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.

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.

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.

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.

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

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

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:

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.

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

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.

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.

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.

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.

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.

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.

kontrl.table({
  
  // Other settings

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

You can choose change the toolbar to include all default QuillJS functionality. More info in the QuillJS documentation

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

// 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

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

The same can be done with beforeCreate

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

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.

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

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.

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

const customType = kontrl.customType({

  // Other settings

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