Skygear CMS - README

skygear-cms-readme.md

CMS Plugin for Skygear

This is a Skygear Plugin to provide CMS functionality to your app.

Installation

It is easy to use CMS in your Skygear app on the cloud. To do that, add the following line in your index.js in the root of your repo:

require('skygear-cms');

After commit, push your changes to Skygear Cloud. If you do not have an app yet, create one at Skygear Portal.

Usage

The CMS adds a admin page under https://<appname>.skygeario.com/cms. You can browse to this page using a web browser.

The admin page allows any user with admin role to manage data. By default, Skygear Server creates a user with admin role when running for the first time.

Log in as admin and use the default password secret to use the default admin account.

Local Development

You can add the CMS plugin to your app for local development. First of all, you need to add CMS as a dependency using npm.

$ npm install git+ssh://git@github.com/oursky/skygear-cms.git --save

After that, require skygear-cms by adding the following line in index.js:

require('skygear-cms');

Try out locally

You need Docker for Mac to try out the CMS locally.

# Clone this repo
$ git clone git@github.com:oursky/skygear-cms.git
$ cd skygear-cms
$ npm install

# Run backing services
$ docker-compose up -d db

# Run skygear-server and plugin
$ docker-compose up app plugin

Your CMS will appear at http://localhost:3000/cms.

Customization

By default, the CMS will show your records in the web interface according to the database schema. It is likely that you will want to change this configuration to customize the web interface.

Since CMS is based on ng-admin, we support all the configuration options available to ng-admin. To get started, take a look at the ng-admin documentation.

CMS generates a default configuration, which is a good starting point for customization. You can download the default configuration from https://<appname>.skygeario.com/cms/cms-config.js.

After modifying the configuration file, you need to save the config to cms-config.js in your app repo root. Changes will apply when you restart the app.

Support auto-completion for reference fields

For reference fields, it is possible to support auto-completion so that the user can type a few characters to find the referenced record instead of looking for the referenced record from a long list.

You can use auto-completion in two places: the filtering in list view and the dropdown box in edit view.

Manual configuration is needed to support auto-completion.

Filtering with reference field in list view

If you want to add filter in list view, you can configure it as follows:

user_conversation.listView().filters([
  nga.field('unread_count', 'number'),
  nga.field('conversation', 'reference')
    .targetEntity(conversation).targetField(nga.field('title'))
    .remoteComplete(true, {
      searchQuery: function(search) {
        return {
          _q: {
            title: search
          }
        };
      }
    })
);

The above configuration will give the user two filters: one for unread_count and another one for conversation. The remoteComplete configuration allows end-user to select a conversation record using case-insensitive partial match of the title field (ilike operation in PostgreSQL).

Auto-completion in edit view

If your reference field is editible, you can add remoteComplete to your nga.field declaration so that it will be turned into a auto-completion text field with dropdown box for selection.

user_conversation.editionView().fields([
  nga.field('_id').editable(false),
  nga.field('conversation', 'reference')
    .targetEntity(conversation).targetField(nga.field('title'))
    .remoteComplete(true, {
      searchQuery: function(search) {
        return {
          _q: {
            title: search
          }
        };
      }
    })
);

The above configuration will use the conversation.title field for auto-completion. The dropdown box will only list the conversation which title contains the user input string.

Record ACLs

ACL is associated with record to control who have certain access to a record. Skygear Server provides support for default ACL settings when creating new record. If you want to apply custom ACL when user create or modify records using CMS, you need to provide manual configuration.

Custom default ACL when creating records

You can provide custom defaults for ACL when creating records. This is achieved by setting a default value using defaultValue.

nga.field('_access', 'json')
.defaultValue([
  {public: true, level: "read"},
  {role: "teacher", level: "write"}
])
.template('', true) // hide the field from creation form

In the above example, the user who has teacher role will have write access to the created record while other users will have read role to the record.

Custom ACL when modifying records

If you do not specify custom configuration, ACL of a record remains unchaged when end-user modify the record using CMS. If you want to allow end-user to change the ACL of a record, you should give the user a few access control options to choose from.

In this example, the user can decide whether the record is public readable or public writable:

nga.field('_access', 'choice').defaultValue('public-readable').choices([
  { value: 'public-readable', label: 'Public Readable' },
  { value: 'public-writable', label: 'Public Writable' }
]).map(function (value) {
  return value[0].level === 'read' ? 'public-readable' : 'public-writable';
}).transform(function (value) {
  return value === 'public-readable' ? 
    [{'public': true, 'level': 'read'}] :
    [{'public': true, 'level': 'write'}];
}),