Have you seen our new video tutorials? Check it out!

Checkboxes Field Type

The checkboxes field type provides a multiple checkbox input.

Introduction

anomaly.field_type.checkboxes

The checkboxes field type provides an input with a series of multiple checkbox options.

Configuration

Below is the full configuration available with defaults values:

"example" => [
    "type"   => "anomaly.field_type.checkboxes",
    "config" => [
        "default_value" => null,
        "options"       => null,
        "min"           => null,
        "max"           => null,
        "mode"          => "checkboxes",
        "handler"       => "Anomaly\CheckboxesFieldType\[email protected]"
    ]
]
Configuration
Key Example Description

default_value

foo

The default value key.

options

["foo" => "Foo", "bar" => "Bar"]

The option array. Values may optionally be non-keyed.

min

3

The minimum selections allowed.

max

10

The maximum selections allowed.

mode

tags

The input mode. Valid options are checkboxes and tags.

handler

\Example\Test\[email protected]

The option handler. You may also specify countries or states to use alternate built-in handlers.

Option Groups

Checkbox options can be organized into groups by nesting the options into keyed groups. The key is translated as the group's label.

"options" => [
    "module::message.examples" => [
        "foo" => "FOO",
        "bar" => "BAR",
    ],
    "module::message.tests" => [
        "baz" => "BAZ",
    ],
]

Option Handlers

Option handlers are responsible for setting the available options on the field type. You can define your own option handler to add your own logic to available options.

You can define custom handlers as a callable string where @handle will be assumed if no method is provided:

"handler" => \App\Example\MyOptions::class // Assumes @handle

Option handlers can also a handler with a closure:

"example" => [
    "config" => [
        "handler" => function (CheckboxesFieldType $fieldType) {
            $fieldType->setOptions(
                [
                    "foo" => "FOO",
                    "bar" => "BAR"
                ]
            );
        }
    ]
]
Remember: Closures can not be stored in the database so your closure type handlers must be set / overridden from the form builder.
Writing Option Handlers

Writing custom option handlers is easy. To begin create a class with the method you defined in the config option.

"handler" => "[email protected]"

The handler string is called via Laravel's service container. The CheckboxesFieldType $fieldType is passed as an argument.

Pro Tip: Handlers are called through Laravel's service container so method and class injection is supported.
<?php namespace App/Example;

class MyOptions
{
    public function handle(CheckboxesFieldType $fieldType)
    {
        $fieldType->setOptions(
            [
                "foo" => "FOO",
                "bar" => "BAR"
            ]
        );
    }
}

Usage

This section will show you how to use the field type via API and in the view layer.

Setting Values

You must set the value for a checkboxes field type with a key or keys from the available options:

$entry->example = "foo";

You can set multiple values with an array:

$entry->example = ["foo", "bar"];

Basic Output

The addon field type returns an array of value keys.

$entry->example; // ["foo", "bar"]

Presenter Output

This section will show you how to use the decorated value provided by the \Anomaly\CheckboxesFieldType\CheckboxesFieldTypePresenter class.

CheckboxesFieldTypePresenter::count()

The count method returns the number of selected options.

Returns: integer
Example
$decorated->example->count();
Twig
{{ decorated.example.count() }}

CheckboxesFieldTypePresenter::total()

The total method returns the total number of available options.

Returns: integer
Example
$decorated->example->total();
Twig
{{ decorated.example.total() }}

CheckboxesFieldTypePresenter::keys()

The keys method returns an array of selected value keys.

Returns: array
Example
$decorated->example->keys();
Twig
{{ decorated.example.keys() }}

CheckboxesFieldTypePresenter::values()

The values method returns an array of selected values.

Returns: array
Example
$decorated->example->values();
Twig
{{ decorated.example.values() }}

CheckboxesFieldTypePresenter::selections()

The selections method returns an associated array of selected key => value pairs.

Returns: array
Example
$decorated->example->selections();
Twig
{{ decorated.example.selections() }}