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}.jsfile in./lib/fieldTypesthat controls the field and encapsulates options support, underscore functions, validation and updating - the
{fieldType}.jsfile needs to be included by./lib/fieldTypes/index.js - a
form.jadefile 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.jadetemplate 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
processFiltersandgetSearchFiltersmethods 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 intosearch.jadetemplates with theform.jade,initial.jadeones 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.
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 ownaddToSchemamethod, this is the data type that will be added to the mongoose Schemathis._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
itemas their first argument. See thecropmthod in./lib/fieldTypes/text.jsfor an example.
- methods bound as underscore methods should take
options.nofilterstops 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.nosortstops 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!
Client-side scripts for specific field types appear to be mostly included by ../templates/views/item.jade as opposed to ../templates/layout/base.jade