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

Configuring the CMS record page

In CMS basics we learn that the CMS is consisted of 2 types of pages: record and user_management. In this section, we will go into details of the record page configuration.

A record page has 4 views: list, show, edit and new. They are the ways your business users read (list, show), update (edit) or create (new) a record in the CMS.

List view

Skygear CMS List View

You can imagine the list view as a spreadsheet that lists out all the records you have in a table.

Example usage:

Assume we have the following tables in our app.

Blogpost

Fields Type
_id String
_created_at DateTime
_updated_at DateTime
title String
content String
cover Asset

Comment

Fields Type
_id String
_created_at DateTime
_updated_at DateTime
comment String
blogpostId Reference

This is what we need:

  1. Display only the title, the content, the cover and the created time of a blogpost.
  2. Show the comments a blog post has.
  3. Users can filter blog posts with title keywords.
  4. Display only blog posts that are created in 2018.
  5. Blog posts sorted in descending order based on their created time.

Then we should write in the YAML file:

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

records:
  comment: 
    record_type: comment
  blogpost:
    record_type: blogpost
    list:
      fields: 
        - name: title
          type: string
          label: Title
        - name: content
          type: text_area
          label: Content
        - name: cover
          type: image
          label: Cover
        - name: _created_at
        - name: blogpost_comment
          label: Comments
          type: reference_list
          reference_via_back_reference: comment
          reference_from_field: blogpostId
          reference_field_name: comment
      filters:
        - name: title
          type: string
          label: Title
      predicates:
        - name: _created_at
          predicate: greater_than_or_equal_to
          value: 2018-01-01
      default_sort:
        name: _created_at
        ascending: false

List view configurable items

record_type

record_type: database table name

It refers to the database table the CMS record is linked to. In the above example, the CMS record blogpost is linked to the database table blogpost.

fields

fields:
  - name: field name in the database
    type: CMS record type # see the field type guide
    label: name to display in the CMS

It refers to the fields you want to display. You may not want to display all the fields of a record as it may confuse your business users. For example, most developers choose to not display the record id.

There are three reserved fields you can use:

fields:
  - name: _id
  - name: _created_at
  - name: _updated_at

Besides, when you configure a field, you have to specify its field types. Field types in the CMS is not equivalent to data type the database. They are the way the CMS displays the content of the field. For example, as blog posts are usually long texts, using text_area to display the content field maybe more appropriate. You can learn about all the field types in the CMS field type guide.

filters

filters:
  - name: field name in the database
    type: filter type 
    label: name to display in the CMS

It refers to the fields your business users can use to filter the records. For example, if you set the title field to be filterable, then the business users can filter blog posts that contains a specific keyword in its title.

filter type determines the filter format. For example, if the filter type is string, a keyword search filter will be used.

Below are the filter type you can use:

  • string
  • date_time
  • boolean
  • integer
  • general
  • reference

You can have multiple filters. All filters can be accessed by pressing the 'filter' button on the upper right corner.

predicates

predicates:
  - name: database field name
    predicate: predicate
    value: value the predicate based on

Different from filter, predicates will be applied to the list view automatically. For example, if we only want to show blog posts created in 2018, we can apply a predicate to the _created_at field.

Below are the predicates you can use:

  • like
  • not_like
  • case_insensitive_like
  • case_insensitive_not_like
  • equal_to
  • not_equal_to
  • greater_than
  • greater_than_or_equal_to
  • less_than
  • less_than_or_equal_to
  • contains
  • not_contains
  • contains_value
  • not_contains_value

Example usage:

Suppose we want to display blogpost that are created in 2018 only.

list:
  predicates:
    - name: _created_at
      predicate: greater_than
      value: 2018-01-01

Note: for date value, we support what YAML supports. Check it out the YAML spec for datetime here.

default_sort

default_sort:
  name: database field name
  ascending: true or false

It refers to the fields you want to use to order your records.

actions

Skygear actions

actions:
  - type: add_button
  - type: import    
    name: name configured in the import section
    label: Text to show inside the button
    atomic: true or false (optional)
  - type: export
    name: name configured in the export section
    label: Text to show inside the button
  - type: link
    label: Text to show inside the button
    href: link path
    target: HTML link target attribute

By default, there will be two buttons on the upper right hand corner: 'Add' and 'Add Filter'. On top of that, you can create more action buttons by configuring actions.

There are 4 action types:

  • import: import data with a CSV
  • export: import data to a CSV
  • link: any custom link
  • add_button: create a new record

If you want to use the import and export function, you also need to configure the import or the export settings. Read the 'CMS Import and Export' guide to learn more.

item_actions

Skygear item actions

item_actions: 
  - type: show_button
  - type: edit_button
  - type: link
    label: Text to show inside the button
    href: link path
    target: HTML link target attribute

There are buttons next to every record, and they are called 'item actions'. If you have enabled the edit and the show view, by default there are two buttons next to each record: show and edit.

To add custom buttons, simply configure item_actions. For example, you may add a button next to each record that links users to the Google search results of the record's title.

  - type: link
    label: Search
    href: https://www.google.com/search?q={record.title}
    target: _blank

Show, edit and new view

Show view CMS show

Edit view CMS edit

New view CMS new

As suggested by their names:

  1. show refers to the detail page where users can see the details of an individual record
  2. edit refers to the edit page where users can update a record
  3. new refers to the create page where users can create a record.

Since fields is the only configurable item of the 3 views, the below example will demonstrate how to configure them in one go.

Note: you can have different CMS field type for the same field for different views. For example, you may use text_area to display the blog post's content in the list view and wysiwyg in the new view. In the CMS field type guide, you will see all the available field types and their respective UI views.

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

records:
  comment: 
    record_type: comment
  blogpost:
    record_type: blogpost
    list:
      fields:
        - name: title
          type: string
          label: Title
        - name: content
          type: text_area
          label: Content
        - name: cover
          type: image
          label: Cover
        - name: _created_at
        - name: blogpost_comment
          label: Comments
          type: reference_list
          reference_via_back_reference: comment
          reference_from_field: blogpostId
          reference_field_name: comment
      actions:
        - type: add_button
        - type: link
          label: Custom button
          href: https://skygear.io
          target: _blank
      item_actions:
        - type: show_button
        - type: edit_button
        - type: link
          label: Custom button
          href: https://skygear.io
      filters:
        - name: title
          type: string
          label: Title
      predicates:
        - name: _created_at
          predicate: greater_than_or_equal_to
          value: 2018-01-01
      default_sort:
        name: _created_at
        ascending: false
    show:
      fields:
        - name: title
          type: string
          label: Title
        - name: content
          type: text_area
          label: Content
        - name: cover
          type: image
          label: Cover
        - name: _created_at
        - name: blogpost_comment
          label: Comments
          type: reference_list
          reference_via_back_reference: comment
          reference_from_field: blogpostId
          reference_field_name: comment
    edit:
      fields:
        - name: title
          type: string
          label: Title
        - name: content
          type: wysiwyg
          label: Content
        - name: cover
          type: image
          label: Cover
        - name: _created_at
        - name: blogpost_comment
          label: Comments
          type: reference_list
          reference_via_back_reference: comment
          reference_from_field: blogpostId
          reference_field_name: comment
    new: 
      fields:
        - name: title
          type: string
          label: Title
        - name: content
          type: wysiwyg
          label: Content
        - name: cover
          type: image
          label: Cover
        - name: _created_at
        - name: blogpost_comment
          label: Comments
          type: reference_list
          reference_via_back_reference: comment
          reference_from_field: blogpostId
          reference_field_name: comment

If the 4 views share the same fields config, you can use anchors to save time.

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

records:
  comment: 
    record_type: comment
  blogpost:
    record_type: blogpost
    list:
      fields: &blogpost_fields
        - name: title
          type: string
          label: Title
        - name: content
          type: text_area
          label: Content
        - name: cover
          type: image
          label: Cover
        - name: _created_at
        - name: blogpost_comment
          label: Comments
          type: reference_list
          reference_via_back_reference: comment
          reference_from_field: blogpostId
          reference_field_name: comment
      actions:
        - type: add_button
        - type: link
          label: Custom button
          href: https://skygear.io
          target: _blank
      item_actions:
        - type: show_button
        - type: edit_button
        - type: link
          label: Custom button
          href: https://skygear.io
      filters:
        - name: title
          type: string
          label: Title
      predicates:
        - name: _created_at
          predicate: greater_than_or_equal_to
          value: 2018-01-01
      default_sort:
        name: _created_at
        ascending: false
    show:
      fields: *blogpost_fields
    edit:
      fields: *blogpost_fields
    new: 
      fields: *blogpost_fields

What's next?

Next, check out the field types supported by the Skygear CMS.