Creating Lists

Usage

keystone.createList('Post', {
  /* ...config */
});

Config

fields

Defines the fields to use in a list.

Usage

keystone.createList('Post', {
  fields: {
    title: { type: Text },
  },
});

See: Fields for more information on configuring field options.

schemaDoc

A description for the list used in the GraphQL schema.

hooks

Specify functions to be executed during list operations. Supported hooks include:

• Create and update operations
  • resolveInput
  • validateInput
  • beforeChange
  • afterChange
• Delete operations
  • validateDelete
  • beforeDelete
  • afterDelete

See List Hooks in the API docs and the Hooks Guide for details.

Usage

keystone.createList('User', {
  fields: {
    name: { type: Text },
  },
  hooks: {
    resolveInput: ({ resolvedData }) => {
      return {
        name: `${resolvedData.name} the Great!`,
      };
    },
  },
});

label

Overrides label for the list in the AdminUI. Default is listName.

labelField

Specify a field to use as a label for individual list items.

Usage

keystone.createList('User', {
  fields: {
    name: { type: Text },
    email: { type: Text },
  },
  labelField: 'name',
});

labelResolver

Function to resolve labels for individual list item. Default resolves the labelField.

Usage

keystone.createList('User', {
  fields: {
    name: { type: Text },
    email: { type: Text },
  },
  labelResolver: item => `${item.name} - ${item.email}`,
});

access

Access control options for the list.

Options for create, read, update and delete - can be a function, GraphQL where clause or Boolean. See the access control API documentation for more details.

Usage

keystone.createList('User', {
  fields: {
    name: { type: Text },
  },
  access: {
    read: false,
  },
});

adminConfig

Options for the AdminUI including:

• defaultPageSize
• defaultColumns
• defaultSort
• maximumPageSize

Usage

keystone.createList('User', {
  fields: {
    name: { type: Text },
    email: { type: Text },
  },
  adminConfig: {
    defaultColumns: 'name,email',
    defaultPageSize: 50,
    defaultSort: 'email',
    maximumPageSize: 100,
  },
});

itemQueryName

Changes the item name in GraphQL queries and mutations.

Usage

keystone.createList('User', {
  fields: {
    name: { type: Text },
  },
  itemQueryName: 'Person',
});

With the above example a GraphQL query might look like this:

query {
  Person(where: {id: "1"}) {
    name
  }
}

listQueryName

Changes the list name in GraphQL queries and mutations.

Usage

keystone.createList('User', {
  fields: {
    name: { type: Text },
  },
  listQueryName: 'People',
});

With the above example a GraphQL query might look like this:

query {
  allPeople {
    name
  }
}

singular

KeystoneJS list names should be singular and KeystoneJS will attempt to determine a plural.

Where KeystoneJS can't determine a plural you may be forced to use a different list name.

The singular option allows you to change the display label for singular items.

E.g. KeystoneJS can't determine a plural for 'Sheep'. Let's change the singular option:

keystone.createList('WoolyBoi', {
  fields: {
    sheepName: { type: Text },
  },
  singular: 'Sheep',
  plural: 'Sheep',
});

Note: This will override labels in the AdminUI but will not change graphQL queries. For queries and mutations see: itemQueryName and listQueryName.

plural

KeystoneJS will attempt to determine a plural for list items. Sometimes KeystoneJS will not be able to determine the plural forcing you to change the list name. Or sometimes KeystoneJS may get it wrong, especially for non-English words.

E.g. KeystoneJS thinks the correct plural for Octopus is "Octopi". Everyone knows the scientifically accurate plural is "Octopodes":

keystone.createList('Octopus', {
  fields: {
    legs: { type: Integer },
  },
  plural: 'Octopodes',
});

path

Changes the path in the Admin UI. Updating plural and singular values will not change the route in the admin UI. You can specify this using path.

adapterConfig

Override the adapter config options for a specific list. Normally adapterConfig is provided when initialising KeystoneJS:

const keystone = new Keystone({
  name: 'my-project',
  adapter: new Adapter({
    /* ...adapterConfig */
  }),
});

Specifying an adapter config on a list item will extend the default config for this list.

plugins

An array of functions that modify config values. Plugin functions receive a config object and can modify or extend this. They should return a valid list config.

const setupUserList = ({ fields, ...config }) => {
  return {
    ...config,
    fields: {
      ...fields,
      name: { type: Text },
      password: { type: Password },
    },
  };
};

keystone.createList('User', {
  plugin: [setupUserList],
});

This provides a method for packaging features that can be applied to multiple lists.

queryLimits

Configuration for limiting the kinds of queries that can be made against the list, to avoid queries that might overload the server.

See also global query limits on the Keystone object.

• maxResults: maximum number of results that can be returned in a query (or subquery)

keystone.createList('Post', {
  fields: {
    title: { type: Text },
  },
  queryLimits: {
    maxResults: 100,
  },
});

cacheHint

HTTP cache hint configuration for list. (See Apollo docs and HTTP spec.)

• scope: 'PUBLIC' or 'PRIVATE' (corresponds to public and private Cache-Control directives)
• maxAge: maximum age (in seconds) that the result should be cacheable for

Cache headers need to be enabled in the GraphQLApp instance:

const app = new GraphQLApp({
  apollo: {
    tracing: true,
    cacheControl: {
      defaultMaxAge: 3600,
    },
  },
  ...otherGraphqlOptions,
});

See also the Apollo cache control doc.

PRIVATE is a recommendation that browsers should cache the result, but forbids intermediate caches (like CDNs or corporate proxies) from storing it. It needs to be used whenever the result depends on the logged in user (including secrets and user-specific content like profile information). If the result could be different when a user logs in, PRIVATE should still be used even if no user is logged in.

keystone.createList('Post', {
  fields: {
    title: { type: Text },
  },
  cacheHint: {
    scope: 'PUBLIC',
    maxAge: 3600,
  },
});

Cache hints can be dynamically returned from a function that takes an object with these members:

• results: an array of query results
• operationName: the name of the GraphQL operation that generated the results
• meta: boolean value that's true for a meta (count) query

keystone.createList('Post', {
  fields: {
    title: { type: Text },
  },
  cacheHint: ({ meta }) => {
    if (meta) {
      return {
        scope: 'PUBLIC',
        maxAge: 3600,
      };
    } else {
      return {
        scope: 'PRIVATE',
        maxAge: 60,
      };
    }
  },
});