You are viewing Skygear v1 Documentation.Switch to Skygear v0 Documentation

CMS field types

Introduction
Supported field types
What's next?

Introduction

When you configure fields of a CMS record, you need to define the type of each field.

records:
  blogpost:
    record_type: blogpost
      list:
        fields:
          - name: content
            type: string # CMS field types
            label: Content

Field type =/= Data type

Field type in Skygear CMS refers to the UI presentation of the field, not its data type in the database.

For example, suppose there are two roles in your app: student and teacher. In the user table, there is a column named 'role' the stores the role of the user. 'role' in the database has a data type of string, however, in the CMS, you can set the its field type to dropdown to limit the input to student or teacher.

records:
  user:
   record_type: user
     list:
       fields:
          - name: role
            type: dropdown # CMS field types
            label: Role
            options:
              - label: Teacher
                value: teacher
              - label: Student
                value: student

You can use different field type for the same field in different views

A CMS record has 4 views: list, show, edit and new. It is likely that the 4 views have similar fields. However, considering the UI presentation of the 4 views are different, you may want to use different field type in different view.

Reusing the teach and student example. Suppose you want to display the role as string, however, when users edit or create a new user, you want to display the role field as dropdown so that you can limit the user input to student or teacher.

records:
  blogpost:
    record_type: user
      list:
        fields:
          - name: role
            type: string
            label: Role
      show:
        fields:
          - name: role
            type: string
            label: Role      
      edit:
        fields:
          - name: role
            type: dropdown
            label: Role
      new:
        fields:
          - name: role
            type: dropdown
            label: Role

Supported field types

Every field type has two views: display and edit. Display view default will be applied to the list and the show view, while edit view default will be applied to the edit and new view.

For example, if you use wysiwyg in the list or the show view, you will get the default WYSIWYG display view (a HTML preview WYSIWYG widget). If you use wysiwyg in the edit or new view, you will get the default WYSIWYG edit view (a working WYSIWYG editor).

Category	Field type	Display view	Edit view
Text	`string`	Single-line text	Single-line text input
	`text_area`	Mulitple-line text	Mulitple-line text input
	`wysiwyg`	HTML preview WYSIWYG widget	WYSIWYG Eidtor
	`dropdown`	Non-expandable dropdown	Dropdown input
Number	`number`	Number display	Number input
	`float`	Float display	Float input
	`integer`	Integer display	Integer input
Files	`asset`	Asset name	Asset uploader
Files	`image`	Image display	Image uploader
Relational records	`reference` (1-many)	Text display	Dropdown input
	`reference_list` (many-1 or many-many)	Text display	Dropdown input
	`embedded_reference`	Coming soon
	`embedded_reference_list`	Coming soon
Time	`date_time`	Date time display	Date and time picker
Time	`date`	Coming soon
Boolean	`boolean`	Non-editable switch	Switch
Location	`location`	Coming soon
Location	`map`	Coming soon
JSON	`json`	Coming soon

`string`

Single-line text.

fields:
  - name: database field name
    type: string
    default_value: default value # applicable only to the new view
    editable: true or false # applicable only to the edit and the new view

`text_area`

Multiple-line text

fields:
  - name: database field name
    type: text_area
    default_value: default value # applicable only to the new view
    editable: true or false # applicable only to the edit and the new view

`wysiwyg`

WYSIWYG with HTML markups. If you use wysiwyg in the edit and the new view, we also suggest you using wysiwyg in the list and the show view so that your users can see the HTML preview instead of raw HTML.

fields:
  - name: database field name
    type: wysiwyg
    config: tiny wysiwyg config
    default_value: default value # applicable only to the new view
    editable: true or false # applicable only to the edit and the new view

config: Skygear CMS uses WYSIWYG editor from Tinymce. Therefore, you can configure the WYSIWYG editor according to the Tinymce doc. Below is the configuration Skygear CMS is currently using.

{
  height: 480,
  plugins:
    'anchor charmap code colorpicker contextmenu fullscreen hr image imagetools link lists nonbreaking paste tabfocus table textcolor',
  skin_url: 'tinymce/skins/lightgray',
  toolbar1:
    'bold italic strikethrough forecolor backcolor | link image | alignleft aligncenter alignright alignjustify  | numlist bullist outdent indent  | removeformat',
}

Example usage:

Suppose we want to add another toolbar to the editor:

fields:
  - name: database field name
    type: wysiwyg
    config:
      toolbar2: paste | copy | undo | redo

`dropdown`

Currently dropdown only support string inputs.

fields:
  - name: database field name
    type: dropdown
    custom: 
      enabled: true or false
      label: name of the custom value
    null: 
      enabled: true or false
      label: name of the null values
    options:
      - label: option 1
        value: A # only string inputs are supported
      - label: option 2
        value: B
    default_value: default value # applicable only to the new view
    editable: true or false # applicable only to the edit and the new view

custom: When custom is enabled, users will be given an 'other' option and be able to enter custom value. Default is false.
null: When null is enabled, users can submit a null value. You can also give a display name to the null value (i.e. undefined). Default is false.
options: All available options.

`number`

fields:
  - name: database field name
    type: number
    default_value: default value # applicable only to the new view
    editable: true or false # applicable only to the edit and the new view

`float`

fields:
  - name: database field name
    type: float
    default_value: default value # applicable only to the new view
    editable: true or false # applicable only to the edit and the new view

`integer`

fields:
  - name: database field name
    type: integer
    default_value: default value # applicable only to the new view
    editable: true or false # applicable only to the edit and the new view

`asset`

Files except images.

fields:
  - name: database field name
    type: asset
    accept: the accepted file types
    nullable: 
      enabled: true or false
    editable: true or false # applicable only to the edit and the new view

nullable: nullable only applies to the edit and the new view. When nullable is enabled, users can update or create a record even if the asset field is null. When nullable is disabled, users must upload an asset when they edit or create a record.
type: Read the MDN web doc here to learn more about the file types.

`image`

fields:
  - name: database field name
    type: image
    nullable: 
      enabled: true or false
    editable: true or false # applicable only to the edit and the new view

nullable: nullable only applies to the edit and the new view. When nullable is enabled, users can update or create a record even if the image field is null. When nullable is disabled, users must upload an image when they edit or create a record.

`reference`

1-to-1 relational records.

fields:
  - name: database field name
    type: reference
    reference_target: Referenced CMS record
    reference_field_name: Referenced record field name
    editable: true or false # applicable only to the edit and the new view

Example usage:

Suppose we have a comment table with every comment associated to a blogpost, and you want to show the blogpost's title next to the comments.

site:
  type: record
  name: comment
  label: Comment

records:
  blogpost: 
    record_type: blogpost
  comment:
    record_type: comment
    list: 
      fields: &blogpost_reference_field
        - name: blogpostId
          type: reference
          reference_target: blogpost
          reference_field_name: title
    show: 
      fields: *blogpost_reference_field
    edit:
      fields: *blogpost_reference_field
    new:
      fields: *blogpost_reference_field

`reference_list`

Many-to-1 and/or many-to-many relation records.

many-to-1

fields:
  - name: a random name
    type: reference_list
    reference_via_back_reference: the table the field refers to
    reference_from_field: the field that links the two tables
    reference_field_name: the field you want to display
    editable: true or false # applicable only to the edit and the new view

Example usage:

Suppose we have a comment table with every comment referenced to a blogpost, and you want to show all the comments a blogpost has.

site:
  type: record
  name: blogpost
  label: Blogpost

records:
  comment: 
    record_type: comment
  blogpost:
    record_type: blogpost
      list: 
        fields: &comment_reference_field
          - name: blogpost
            type: reference_list
            reference_via_back_reference: comment
            reference_from_field: blogpostId
            reference_field_name: comment
      show: 
        fields: *comment_reference_field
      edit:
        fields: *comment_reference_field
      new:
        fields: *comment_reference_field

many-to-many

fields:
  - name: random
    reference_via_association_record: association record name
    reference_target: desired table
    reference_field_name: desired fields
    editable: true or false # applicable only to the edit and the new view

Displaying a many-to-many relational records in Skygear CMS is a little tricky. We call the intermediate tables that connect two tables association records. You need to configure the association record before you can display a many-to-many relation record.

Example usage:

Suppose we have an intermediate table named blogpost_comment that connects the blogpost and comment table. We want to show all the comments a blogpost has.

site:
  - type: record
    name: blogpost
    label: blogpost

records:
  comment: 
    record_type: comment
  blogpost:
    record_type: blogpost
    list:
      fields:
        - name: random name
          type: reference_list
          reference_via_association_record: blogpost_comment
          reference_target: comment
          reference_field_name: content

association_record:
  blogpost_comment:
    - name: blogpostId
      type: reference
      reference_target: blogpost
    - name: commendId
      type: reference
      reference_target: comment

`date_time`

Date with time.

fields:
  - name: database field name
    type: date_time
    timezone: timezone
    default_value: default value # applicable only to the new view
    editable: true or false # applicable only to the edit and the new view

timezone: Setting the timezone of a Datetime field will override the default timezone setting. The timezone list can be found here. Use the TZ convention (e.g. Africa/Abidjan).

`boolean`

Switch.

fields:
  - name: database field name
    type: boolean
    default_value: true or false # applicable only to the new view
    editable: true or false # applicable only to the edit and the new view

What's next?

Next, let's learn about how to configure import and export.