Notes on how to create a new field type for Keystone

notes.md

Creating new Field Types for KeystoneJS

We're currently working on making it easier to add new field types to KeystoneJS as plugins.

In the meantime, if you'd like to work on your own field type, hopefully this guide will point you in the right direction.

Keystone fields require the following:

• a {fieldType}.js file in ./lib/fieldTypes that controls the field and encapsulates options support, underscore functions, validation and updating
• the {fieldType}.js file needs to be included by ./lib/fieldTypes/index.js
• a form.jade file in ./templates/fields/{fieldType} that renders the form field for the element
• if the field should be available when creating new items (not all types are) then it'll also need an initial.jade template in ./templates/fields/{fieldType} that renders the form field for the create form
• unless it's a text-type field with no special formatting for the list view, also add support for it in ./templates/mixins/columns.jade

If the field type requires an async callback to handle updates, e.g. file upload, support should be added to the process method in ./lib/updateHandler.js.

To implement filtering on the field type in the list view, you'll need to add

• support for it in the processFilters and getSearchFilters methods in ./lib/list.js
• a template to render the search interface in ./templates/views/list.jade (around line 170 or so) - this should be broken up into search.jade templates with the form.jade, initial.jade ones but it hasn't happened yet!

Finally, some field types add their own client-side javascript or css that needs to be included in ./templates/layout/base.jade. Specific styles for different field types are generally implemented in ./public/styles/keystone/forms.less.

The base field class implements a few built-in options and methods that can be set / overridden by each FieldType class. At the moment, it's strongly recommended you understand how ./lib/field.js (the base class) works, and review some of the ways different field types (in ./lib/fieldTypes) are set up to get a feel for how this works.

Some hints:

In the constructor function you can set options that control how the base Field class sets up field types. These include:

• this._nativeType - unless you're providing your own addToSchema method, this is the data type that will be added to the mongoose Schema
• this._underscoreMethods (Array of Strings) - a list of methods on the FieldType class that should be automatically bound as underscore methods to the field
  • methods bound as underscore methods should take item as their first argument. See the crop mthod in ./lib/fieldTypes/text.js for an example.
• options.nofilter stops the field from being included in the drop-down list of available filters on the list view. Set this if you haven't implemented filtering as described above.
• options.nosort stops the field from being used to sort in the list view

If you are implementing a complex field type (by which we mean one that stores a complex value, e.g. the markdown field type, or one that implements middleware / virtuals / etc.) you need to override the addToSchema method. Follow an existing example closely, this method needs to add() to this.schema, and should call this.bindUnderscoreMethods().

validateInput and updateItem should almost always be added, again see existing examples.

Please feel free to reach out to @keystonejs on twitter, on our Google Group or comment on this gist if you've got any questions or get stuck!