Contents

Selection Control Pattern

A selection control at its most basic is a means to select one or more items from a larger set.

The common control module contains a number of common variants:

DropDown
A standard select control
MultiSelectDropDown
A select control allowing multiple selections
CheckSet
A list of checkboxes
RadioButtons
A presentation of radio buttons
SearchControl
For selecting items from large collections this allows you to search a back end store via XHR requests

Defining the list of Items

All selection controls extend SelectionControl and receive a set of available items to present by calling setSelectionItems(). This function receives an array that can contain a whole range of different structures which define the list of items.

To demonstrate the various ways to configure items we'll use the DropDown control.

Defining Fixed Items

The most simple structure is an array of strings:

ItemsByStringView.php
<?php

namespace Rhubarb\Leaf\Controls\Common\Examples\SelectionControls;

use Rhubarb\Leaf\Controls\Common\SelectionControls\DropDown\DropDown;
use Rhubarb\Leaf\Views\View;

class ItemsByStringView extends View
{
    protected function createSubLeaves()
    {
        $this->registerSubLeaf(
            $control = new DropDown("control")
        );

        $control->setSelectionItems(
            [
                "Item 1",
                "Item 2",
                "Item 3"
            ]
        );
    }

    protected function printViewContent()
    {
        print $this->leaves["control"];
    }
}

Populated this way, the values of the items are the same as the labels, so the bound value in this example would be Item 1, Item 2 etc.

To have different values from the labels you need to move from a simple string to an array with two values - the first is the value and the second is the label.

ItemsByArrayView.php
<?php

namespace Rhubarb\Leaf\Controls\Common\Examples\SelectionControls;

use Rhubarb\Leaf\Controls\Common\SelectionControls\DropDown\DropDown;
use Rhubarb\Leaf\Views\View;

class ItemsByArrayView extends View
{
    protected function createSubLeaves()
    {
        $this->registerSubLeaf(
            $control = new DropDown("control")
        );

        $control->setSelectionItems(
            [
                ["", "Please Select"],
                [1, "Item 1"],
                "Item 2",
                "Item 3"
            ]
        );
    }

    protected function printViewContent()
    {
        print $this->leaves["control"];
    }
}

In this example the first two items in the drop down have different values from the text shown in the drop down. Inspect the DOM element in your developer tools to confirm this.

Option groups

Some selection controls support the concept of option groups - a simple way to group related options. Do this by having sub arrays of options keyed by the group name:

ItemsByGroupView.php
<?php

namespace Rhubarb\Leaf\Controls\Common\Examples\SelectionControls;

use Rhubarb\Leaf\Controls\Common\SelectionControls\DropDown\DropDown;
use Rhubarb\Leaf\Views\View;

class ItemsByGroupView extends View
{
    protected function createSubLeaves()
    {
        $this->registerSubLeaf(
            $control = new DropDown("control")
        );

        $control->setSelectionItems(
            [
                "Group 1" => [
                    "Item 1",
                    "Item 2",
                ],
                "Group 2" => [
                    [3, "Item 3"]
                ]
            ]
        );
    }

    protected function printViewContent()
    {
        print $this->leaves["control"];
    }
}

Defining Items from Collections

Pass a collection to have the items created by iteration over the collection.

ItemsByCollectionView.php
<?php

namespace Rhubarb\Leaf\Controls\Common\Examples\SelectionControls;

use Rhubarb\Leaf\Controls\Common\SelectionControls\DropDown\DropDown;
use Rhubarb\Leaf\Views\View;

class ItemsByCollectionView extends View
{
    protected function createSubLeaves()
    {
        $this->registerSubLeaf(
            $control = new DropDown("control")
        );

        $control->setSelectionItems(
            [
                ExampleContact::all()
                    ->addSort("FirstName")
                    ->addSort("Surname")
            ]
        );
    }

    protected function printViewContent()
    {
        print $this->leaves["control"];
    }
}

Make sure your Stem Model's schema has a labelColumnName defined otherwise the selection control won't know how to source the label for the item.

Defining Items from an Enum Column

To present items that stay in-sync with the available possibilities in a model schema's Enum column you can pass a reference to the column schema object.

ItemsByEnumView.php
<?php

namespace Rhubarb\Leaf\Controls\Common\Examples\SelectionControls;

use Rhubarb\Leaf\Controls\Common\SelectionControls\DropDown\DropDown;
use Rhubarb\Leaf\Views\View;

class ItemsByEnumView extends View
{
    protected function createSubLeaves()
    {
        $this->registerSubLeaf(
            $control = new DropDown("control")
        );

        $control->setSelectionItems(
            [
                (new ExampleContact())->getModelColumnSchemaForColumnReference("Status")
            ]
        );
    }

    protected function printViewContent()
    {
        print $this->leaves["control"];
    }
}

This is most useful for driving search options in a list screen or presenting data input fields in a CRUD add/edit screen.

Mixing Definition Methods

All three methods can be mixed in the same configuration:

ItemsByMixedView.php
<?php

namespace Rhubarb\Leaf\Controls\Common\Examples\SelectionControls;

use Rhubarb\Leaf\Controls\Common\SelectionControls\DropDown\DropDown;
use Rhubarb\Leaf\Views\View;
use Rhubarb\Stem\Filters\StartsWith;

class ItemsByMixedView extends View
{
    protected function createSubLeaves()
    {
        $this->registerSubLeaf(
            $control = new DropDown("control")
        );

        $control->setSelectionItems(
            [
                [ "", "Please Select"],
                "Item 1",
                "Item 2",
                [ 3, "Item 3"],
                ExampleContact::all()->addSort("FirstName"),
                ExampleContact::all()->addSort("FirstName", false),
                (new ExampleContact())->getModelColumnSchemaForColumnReference("Status"),
                "Group 1" => [
                    ExampleContact::find(new StartsWith("FirstName", "J"))
                ]
            ]
        );
    }

    protected function printViewContent()
    {
        print $this->leaves["control"];
    }
}