Slug

Generate unique Slugs (aka; keys / url segments) based on the item's data.

Usage

By default, slugs are generated from a name or title field (in that order) if they exist. The field can be specified explicitly with the from option (from: 'username'), or for more advanced use-cases, a generate function can be provided (generate: ({ resolvedData, existingItem }) => mySlugFunc(resolvedData.username))

See the example below for the result of an example mutation.

Using the defaults

As we have specified a title field, its value will be used to generate a unique slug.

const { Slug, Text } = require('@keystonejs/fields');
const { Keystone } = require('@keystonejs/keystone');

const keystone = new Keystone(/* ... */);

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

Specifying a field

The item's username value will be used to generate a unique slug.

const { Slug, Text } = require('@keystonejs/fields');
const { Keystone } = require('@keystonejs/keystone');

const keystone = new Keystone(/* ... */);

keystone.createList('User', {
  fields: {
    username: { type: Text },
    url: {
      type: Slug,
      from: 'username',
    },
  },
});

A custom generate method

const { Slug, Text, DateTime } = require('@keystonejs/fields');
const { Keystone } = require('@keystonejs/keystone');
const slugify = require('slugify');

const keystone = new Keystone(/* ... */);

keystone.createList('Post', {
  fields: {
    title: { type: Text },
    postedAt: { type: DateTime },
    url: {
      type: Slug,
      generate: ({ resolvedData }) => slugify(resolvedData.title + '-' + resolvedData.postedAt),
    },
  },
});

Slug stability

The Slug field attempts to reuse the same value across updates (ie; "stability"). This is particularly important when slugs are used for URL segments to ensure URLs don't change.

For example, if you create an item with a slug abc123, then perform an update mutation without changing any of the data which the slug initial generation was based on, the slug should stay as abc123.

Caveats with Updates and makeUnique

There is one situation where the Slug field cannot guarantee stability; when:

• The regenerateOnUpdate flag is true, and
• Performing an update mutation, and
• A slug value is passed in which is not unique in the list

For example:

1. Perform a create mutation: createPost(data: { slug: "hello-world" }) { slug }.

   • Result: { slug: "hello-world" }

2. Perform a second create mutation with the same slug: createPost(data: { slug: "hello-world" }) { id slug }.

   • Result (approximately): { id: "1", slug: "hello-world-weer84fs" }

3. Perform an update to the second item, with the same slug as the first (again): updatePost(id: "1", data: { slug: "hello-world" }) { id slug }.

   • Result (approximately): { id: "1", slug: "hello-world-uyi3lh32" }
   • The slug has changed, even though we passed the same slug in. This happens because there is no way to know what the previously passed-in slug was, only the most recently uniquified slug (ie; "hello-world-weer84fs").

Workarounds

1. Don't pass in values for the Slug field. Instead, create a generate function which does the work for you in a deterministic way. In this scenario, we are able to compare what would have previously been generated as the slug to the newly generated slug and re-use the old one if they match.
2. Specify a deterministic makeUnique function (the default is to add a random suffix). This will ensure that when the duplicate slug is detected, it will re-generate the same "uniqueified" slug each time. This can be done by adding an incrementing number on each call.

Example

Given the following list config:

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

A mutation to create a new item will auto-generate a slug:

mutation {
  createPost(data: { title: "Why I ♥ KeystoneJS" }) {
    id
    title
    url
  }
}

# Result:
# {
#   createPost: {
#     id: "1",
#     title: "Why I ♥ KeystoneJS",
#     url: "why-i-love-keystonejs"
#   }
# }

Because we've left isUnique at its default value (isUnique: true), a subsequently created item with the same title will generate a unique slug:

mutation {
  createPost(data: { title: "Why I ♥ KeystoneJS" }) {
    id
    title
    url
  }
}

# Result:
# {
#   createPost: {
#     id: "2",
#     title: "Why I ♥ KeystoneJS",
#     url: "why-i-love-keystonejs-2108fh3"
#   }
# }

You can also manually override the slug's value:

mutation {
  createPost(data: { title: "Why I ♥ KeystoneJS", url: "keystonejs-is-great" }) {
    id
    title
    url
  }
}

# Result:
# {
#   createPost: {
#     id: "2",
#     title: "Why I ♥ KeystoneJS",
#     url: "keystonejs-is-great"
#   }
# }

And overwritten slugs will be uniquified for you when isUnique: true (with one caveat):

mutation {
  createPost(data: { title: "Why I ♥ KeystoneJS", url: "keystonejs-is-great" }) {
    id
    title
    url
  }
}

# Result:
# {
#   createPost: {
#     id: "2",
#     title: "Why I ♥ KeystoneJS",
#     url: "keystonejs-is-great-f80p5sm"
#   }
# }

Config

GraphQL

Slug fields use the String type in GraphQL.

Input Fields

Output Fields

Filters