Relationship Field

Stores an ObjectID in the model, which belongs to another List in the system.

When the many: true option is set, it stores an Array [ObjectID] instead.

Displayed as an auto-suggest field in the Admin UI.

Specify the related Model using the ref option. For a many-many relationship, set the many option to true.

Example

Linking to a Post model to a single Author and many PostCategories can be done like this:

Post.add({
    author: { type: Types.Relationship, ref: 'User' },
    categories: { type: Types.Relationship, ref: 'PostCategory', many: true }
});

Methods

getExpandedData()

Expands the stored value into an object containing { id, name } properties.

The name is set by the getDocumentName method on the related List.

In many mode, an array of objects [{ id, name }] is returned.

The relationship path must be populated or this method will return unexpected results.

Example

Post.model.findOne(id)
	.populate('author') // author is a relationship to the User list
	.exec((err, post) => {
		post._.author.getExpandedData() // { id: '1', name: 'Jed Watson' }
	});

format

Returns the stored value as a String.

In many mode, the values in the array will be joined into a comma, space delimited list.

Will return unexpected results if the relationship path has been populated.

updateItem

Updates with the provided value if it is different from the stored value.

undefined values are ignored.

When null is passed, mongoose will remove the path from the stored document and the value will be undefined when the item is next retrieved. This behaviour is different in many mode, when an empty array will be stored.

validateInput

Ensures the value, if provided, is a string (or an array of strings in many mode).

Allows null to clear the field value.

validateRequiredInput

Ensures a value has been provided. Empty strings are not valid.

Filtering

Accepts a value (is an array of ObjectIDs), and can be inverted. Will match any items containing a relationship to any of the provided ObjectIDs in the value array.

{
    inverted: Boolean,
    value: [ObjectID],
}

An empty value will match items containing null (single) or [] (many) stored in the field path.

Inverting the filter finds all items not matching the value.

Default filter arguments are:

{
    inverted: false,
    value: [],
}