Learn

Suggest

The Suggest fieldtype is a one-stop-solution for managing select/multi-select options. You can populate the options with an explicitly defined list, values and labels from any content folder, any taxonomy type, or all three if you really wanted to.

related:
  display: Related Articles
  type: suggest
  create: true
  max_items: 3
  content:
    folder: blog
    label: title
    value: url

General Options

create

Allow the creation of new options in addition to the populated list

Default: false

create: true|false

hide_selected

If true, the items that are currently selected will not be shown in the dropdown list of available options.

Default: true

hide_selected: true|false

persist

If false, items created by the user will not show up as available options once they are unselected.

Default: true

persist: true|false

max_items

Limit the number of items that can be selected. If set to 1, the field becomes a simple select input.

Default: 1000

max_items: 1|100|1000

sort_dir

Sort direction (“asc” or “desc”).

Default: asc

sort_dir: asc|desc

allow_blank

Add a blank option to the field to allow for a blank selection.

Default: false

allow_blank: true

placeholder

Placeholder text to be displayed when no selection is made.

Default: false

placeholder: "Please select a value"

Explicit Options Mode

Use the options key to define your list of explicitly defined options.

In the simple list mode your labels and values will be exactly the same.

options:
  - Steak
  - Pork
  - Bacon wrapped shrimp

You can also define your values and labels separately by using named keys:

options:
  steak: Steak
  pork: Pork
  shrimp: Bacon wrapped shrimp

Content Mode

The Content mode works very much like an Entries Listing tag, and has many of the same options. This is especially useful when combined with Entries Listing conditions to create relationships. Use the content key to define your configuration. Simple example:

content:
  folder: blog
  label: title
  value: url

Options

folder

Specify the folder you wish to fetch content from. You can fetch from multiple folders by pipe delimiting the folder names.

folder: blog|news

label

Specify which custom field you want to use as the label.

Default: title

label: title

value

Specify which custom field you want to use as the stored value.

Default: url

value: url

Filters

type

Show pages or entries.

Default: entries

type: entries|pages|all

show_drafts

Allow entries with draft status to show in the dropdown.

Default: false

show_drafts: true|false

show_hidden

Allow entries with hidden status to show in the dropdown.

Default: false

show_hidden: true|false

since

Filter entries starting at a specified date.

since: July 1st 2013

until

Filter entries ending at a specified date.

until: 2014

conditions

Filter results by field conditions. Works just the like entries:listing tag.

conditions: "featured_post: true,author:jack"

Taxonomy Mode

The Taxonomy mode is useful for displaying a list of all taxonomies used in a specified folder. Use the content key to define your configuration. Simple example:

taxonomy:
  folder: blog
  type: tags

Options

folder

Specify the folder you wish to fetch used taxonomies from.

folder: blog

type

Specify the type of taxonomy you wish to you fetch (e.g. categories, tags, author, etc). Must be defined in your settings.yaml file.

type: categories

Members Mode

The Members mode is useful for displaying a list of all members in your system.

members:
  label: username
  value: _uid

Options

label

Specify which custom field you want to use as the label.

Default: username

label: username

value

Specify which custom field you want to use as the stored value.

Default: _uid

value: _uid

Filters

role

Show members with specific role(s)

Default: all users

role: admin|special

conditions

Filter results by field conditions. Works just the like member:listing tag.

conditions: "handsome: true"

Array Mode

This mode lets you fetch options from an array on another page.

An example of how this could be useful is if you’d like a client to manage categories in one place, and use them as taxonomies in other places. You can use a regular array or a “Grid-style” associative array.

array:
  from: /blog
  field: categories

Options

from

The URL where the array is located.

field

The array’s field name.

key

If the array is a Grid field, you should specify the key field to fetch.

Example

Let’s say on blog/page.md, you have a grid field that holds categories and descriptions, like so:

categories:
  -
    name: News
    description: Read things about things that happened
  -
    name: Events
    description: Where the things happen

Your suggest field used in your blog posts’ fieldset could look like this:

category:
  type: suggest
  max_items: 1
  array:
    from: /blog
    field: categories
    key: name

In your suggest field, your available options will be News and Events.

Note that if you use create: true, the values will not be added to the original array.

This article was last updated on September 13th, 2016. Find an error? Please let us know!