Skip to main content

Custom Predefined Options
LitePro
New in 5.0+

If you wish to supply some of your own predefined option lists that show up inside the Predefined options source for multi-option fields, this is possible with the development of a custom module.

​Setup Guide

The creation of custom predefined options in Freeform will require using a custom Craft module. This guide assumes you already have that knowledge. If not, please check out the guide we have.

View the guide on how to build a custom module.

1

​Prepare the Predefined Options

Let's first create a predefined list of animals, allowing users to choose between three classes: mammals, insects, and birds. Additionally, users will have the option to see either the species of the animals as option labels or the sounds they make.

Create a new file named animals.json in the modules\CustomModule\Animals folder.

// animals.json

[
  {
    "type": "sphynx",
    "sound": "meow",
    "class": "mammal"
  },
  {
    "type": "labrador",
    "sound": "woof",
    "class": "mammal"
  },
  {
    "type": "hummingbird",
    "sound": "tweet",
    "class": "bird"
  },
  {
    "type": "parrot",
    "sound": "tweet",
    "class": "bird"
  },
  {
    "type": "penguin",
    "sound": "tweet",
    "class": "bird"
  },
  {
    "type": "goldfish",
    "sound": "blub",
    "class": "fish"
  },
  {
    "type": "shark",
    "sound": "blub",
    "class": "fish"
  },
  {
    "species": "snake",
    "sound": "hiss",
    "class": "reptile"
  },
  {
    "species": "turtle",
    "sound": "hiss",
    "class": "reptile"
  },
  {
    "species": "lizard",
    "sound": "hiss",
    "class": "reptile"
  }
]
2

​Create a Predefined Option Class

To create a custom predefined options class, you must implement the PredefinedSourceTypeInterface. This interface requires you to define two methods: ::getName(): string and ::generateOptions(): OptionCollection.

Create a new class called AnimalOptions in the modules\CustomModule\Animals folder.

<?php

namespace modules\CustomModule\Animals;

use Solspace\Freeform\Attributes\Property\Implementations\Options\OptionCollection;
use Solspace\Freeform\Attributes\Property\Input\Select;
use Solspace\Freeform\Fields\Properties\Options\Predefined\Types\PredefinedSourceTypeInterface;

class AnimalOptions implements PredefinedSourceTypeInterface
{
    private const DISPLAY_TYPE = 'type';
    private const DISPLAY_SOUND = 'sound';

    private const CLASS_ALL = 'all';
    private const CLASS_MAMMAL = 'mammal';
    private const CLASS_BIRD = 'bird';
    private const CLASS_REPTILE = 'reptile';

    #[Select(
        label: 'Option Label',
        options: [
            self::DISPLAY_TYPE => 'Type',
            self::DISPLAY_SOUND => 'Sound',
        ],
    )]
    private string $label = self::DISPLAY_TYPE;

    #[Select(
        label: 'List by Type',
        options: [
            self::CLASS_ALL => 'All',
            self::CLASS_MAMMAL => 'Mammals',
            self::CLASS_BIRD => 'Birds',
            self::CLASS_REPTILE => 'Reptiles',
        ],
    )]
    private string $listBy = self::CLASS_ALL;

    public function getName(): string
    {
        return 'Animal Options';
    }

    public function generateOptions(): OptionCollection
    {
        $collection = new OptionCollection();

        $json = json_decode(file_get_contents(__DIR__ . '/animals.json'));
        foreach ($json as $animal) {
            $class = $animal->class;
            if ($this->listBy !== self::CLASS_ALL && $class !== $this->listBy) {
                continue;
            }

            $type = $animal->type;
            $sound = $animal->sound;

            $collection->add($type, $this->label === self::DISPLAY_TYPE ? $type : $sound);
        }

        return $collection;
    }
}

We specify the $label as a dropdown choice of Type and Sound, allowing the form administrator to decide which value to use for displaying option labels on the front-end.

We specify $listBy as a dropdown choice of All, Mammals, Birds, and Reptiles, where the form administrator will determine which class of animals to display or choose to display all of them.

Then, in the ::generateOptions() method, we read the animals.json file and generate options based on the selected class and label.

3

​Registering the Custom Predefined Options Class

To register the newly created predefined options in our custom module or plugin, listen to the OptionTypesProvider::EVENT_REGISTER_PREDEFINED_TYPES event.

<?php

namespace modules\CustomModule;

use modules\CustomModule\Animals\AnimalOptions;
use Solspace\Freeform\Events\Forms\RegisterOptionTypesEvent;
use Solspace\Freeform\Fields\Properties\Options\Elements\Types\OptionTypesProvider;
use yii\base\Event;

class Module extends \yii\base\Module
{
    public function init()
    {
        parent::init();

        Event::on(
            OptionTypesProvider::class,
            OptionTypesProvider::EVENT_REGISTER_PREDEFINED_TYPES,
            function (RegisterOptionTypesEvent $event) {
                $event->addType(new AnimalOptions());
            }
        );
    }
}

​Available Property Types

See our Field Properties document for a comprehensive list of available property types you can add to your Predefined Options class properties, allowing you to display them as controls in the builder.

Page Feedback