How to use Suggest Modes in your addon

The “Relate” fields – “Users”, “Taxonomy”, “Collection” – all leverage the “Suggest” field behind the scenes.

While the Relate fields might not look like a Suggest field, they follow the same basic principle: they retrieve “suggestions” through an AJAX call.

Here’s the workflow - we’ll use the “Users” fieldtype as an example:

1. The Users fieldtype Vue component¹ is loaded. It’s basically a wrapper around the Relate fieldtype, but passes a type of user.
2. The Relate fieldtype Vue component² is loaded.
3. The Relate fieldtype performs an AJAX call to /cp/addons/suggest/suggestions, POSTing the field config.
4. That URL corresponds to the Suggest bundle’s Controller³ where it calls ->suggestions() on the appropriate Mode class.
5. In this case, the UsersMode class⁴ is loaded, and gathers the suggestions.

Creating your own Suggest Modes

In step 4 of the workflow above, if you dig into the code, you will notice that it first checks for a Mode class in the Suggest addon, but then checks for a Statamic\Addons\{$mode}\{$mode}SuggestMode class. That’s the secret sauce right there.

To use a custom mode, you can specify the mode in the Suggest field’s config.

We’ll create a mode that gets types of Bacon. This is Statamic after all.

fields:
  things:
    type: suggest
    mode: Bacon

This’ll attempt to load the Statamic\Addons\Bacon\BaconSuggestMode class, so let’s create that at site/addons/Bacon/BaconSuggestMode.php.

<?php namespace Statamic\Addons\Bacon;

use Statamic\Addons\Suggest\Modes\AbstractMode;

class BaconSuggestMode extends AbstractMode
{
    public function suggestions()
    {
        return [
            ['value' => 'applewood', 'text' => 'Applewood'],
            ['value' => 'hickory', 'text' => 'Hickory']
        ];
    }
}

The class should extend the Statamic\Addons\Suggest\Modes\AbstractMode class, and needs to have a single suggestions() method.

The suggestions method needs to return a multidimensional array. As you can see, each suggestion should have a value which will be saved, and the text that will be displayed. You can create this array however you want. Here we’ve just hardcoded it, but you could perform third party API calls, retrieve content, whatever!

You can create optgroups by adding a third optgroup string to each item in the array.

I don’t want it to look like the Suggest field

Well, that’s a different story. It’ll be up to you implement the JS/Vue component.

As long as you perform the AJAX call to /cp/addons/suggest/suggestions, and POST your mode there, you’ll be able to use the suggestion class methods as mentioned earlier.

You can check out the Relate fieldtype Vue component² for inspiration. That’s a completely customized fieldtype that leverages the Suggest modes behind the scenes.