FieldtypeToggle

A yes/no/other toggle with an optional "unknown" (no-selection) state

Unlike FieldtypeCheckbox, Toggle can distinguish between a "no" selection and no selection at all.

Value type

int|string — one of: 1 (yes), 0 (no), 2 (other, if enabled), or '' (unknown / no selection).

Constants: FieldtypeToggle::valueYes (1), ::valueNo (0), ::valueOther (2), ::valueUnknown ('').

Getting and setting values
// Get with output formatting OFF (always int or ''):
$page->of(false);
$page->toggle_field;  // 1, 0, 2, or ''

// Get with output formatting ON (type depends on formatType field setting):
$page->of(true);
$page->toggle_field;  // int, bool, or string label

// Set — accepts int, keyword string, or bool:
$page->toggle_field = 1;         // yes
$page->toggle_field = 0;         // no
$page->toggle_field = 2;         // other (if enabled for field)
$page->toggle_field = '';        // unknown / no-selection
$page->toggle_field = 'yes';     // same as 1
$page->toggle_field = 'no';      // same as 0
$page->toggle_field = 'unknown'; // same as ''
$page->toggle_field = true;      // same as 1
$page->toggle_field = false;     // same as 0
$page->save('toggle_field');
Selectors
// Yes selected
$pages->find('toggle_field=1');
$pages->find('toggle_field=yes');

// No selected
$pages->find('toggle_field=0');
$pages->find('toggle_field=no');

// No selection (unknown)
$pages->find('toggle_field=""');
$pages->find('toggle_field=unknown');

// Yes or no (any selection made)
$pages->find('toggle_field=1|0');

// No or no-selection
$pages->find('toggle_field=0|""');

Note: 0 (no) and '' (unknown/no-selection) are distinct values. toggle_field=0 will not match pages with no selection, and vice versa.

Output / markup

Depends on the formatType field setting (configured under the Details tab):

formatTypeOutput
0 Integer (default)1, 0, 2, or ''
1 Booleantrue / false (no-selection stays '')
2 StringLabel text (e.g. "Yes", "No")
3 EntitiesLabel text, HTML-entity encoded
// formatType=1 (Boolean), output formatting ON:
if($page->toggle_field === true) echo "Yes";
if($page->toggle_field === false) echo "No";
if($page->toggle_field === '') echo "No selection";

// formatType=2 (String), output formatting ON:
echo $page->toggle_field; // outputs "Yes", "No", or custom label
Notes
  • Four states: 1=yes, 0=no, 2=other (optional), ''=unknown/no-selection.
  • With output formatting OFF, always returns int or blank string regardless of formatType.
  • Compatible fieldtypes: FieldtypeToggle, FieldtypeCheckbox.
  • Database column: tinyint NOT NULL, indexed.
API reference: methods, hooks

Toggle fieldtype for “yes/on”, “no/off” and optional “other” state. Unlike FieldtypeCheckbox, this Fieldtype can differentiate between a selection of “no” and no-selection (aka unknown state), and it can also optionally support a selection for “other” (with custom label).

When using a selector to find pages matching a particular toggle state, or when setting values to $page->your_field, the following:

  • 0 or no or FieldtypeToggle::valueNo for no/off selection
  • 1 or yes or FieldtypeToggle::valueYes for yes/on selection
  • 2 or other or FieldtypeToggle::valueOther for other selection (if enabled for field)
  • '' blank string or unknown or FieldtypeToggle::valueUnknown for “no selection”

Please note that 0 and “no selection” are different things (unlike with a checkbox) so be sure to consider this when finding pages or outputting values. The examples below include a couple that demonstrate this.

Examples (for field named “featured”):

// find pages with “yes” selected for “featured”
$items = $pages->find("featured=1");
$items = $pages->find("featured=yes");

// find pages with “no” selected for “featured”
$items = $pages->find("featured=0");
$items = $pages->find("featured=no");

// find pages with no selection
$items = $pages->find("featured=''");
$items = $pages->find("featured=unknown");

// find pages with yes or no selection
$items = $pages->find("featured=1|0");
$items = $pages->find("featured=yes|no");

// find pages with “no” selected, or no selection
$items = $pages->find("featured=''|0");
$items = $pages->find("featured=unknown|no");

// output current value (blank, 0 or 1, or 2 if “other” option available)
// unless you’ve configured it to output custom labels when formatted
echo $page->featured;

// determine current setting (assuming labels not overriding values)
if($page->featured  '') {
  // unknown aka no-selection
} else if($page->featured  0) {
  // no selected
} else if($page->featured  1) {
  // yes selected
} else if($page->featured  2) {
  // other selected (if enabled)
}

// set value of $page->featured to yes/on
$page->featured = 1;

Click any linked item for full usage details and examples. Hookable methods are indicated with the icon. In addition to those shown below, the FieldtypeToggle class also inherits all the methods and properties of: Fieldtype, WireData and Wire.

Show class?     Show args?       Only hookable?    

Common

NameReturnSummary 
FieldtypeToggle::formatValue(Page $page, Field $field, $value)
mixed

Format the given value for output and return a string of the formatted value

FieldtypeToggle::getBlankValue(Page $page, Field $field)
string

Get the blank value

 
FieldtypeToggle::getCompatibleFieldtypes(Field $field)
Fieldtypes null

Get an array of Fieldtypes that are compatible with this one

FieldtypeToggle::getConfigInputfields(Field $field)
InputfieldWrapper

Get any Inputfields used for configuration of this Fieldtype.

FieldtypeToggle::getDatabaseSchema(Field $field)
array

Get database schema

 
FieldtypeToggle::getFieldClass()
string

Get the Field class to use for fields of this type

 
FieldtypeToggle::getInputfield(Page $page, Field $field)
InputfieldToggle

Get the InputfieldToggle instance

 
FieldtypeToggle::getMatchQuery($query, string $table, string $subfield, string $operator, mixed $value)
DatabaseQuerySelect PageFinderDatabaseQuerySelect

@param DatabaseQuerySelect|PageFinderDatabaseQuerySelect $query

 
FieldtypeToggle::getSelectorInfo(Field $field)
array

Get information used for InputfieldSelector interactive selector builder

FieldtypeToggle::markupValue(Page $page, Field $field)
string

Return the markup value

FieldtypeToggle::sanitizeValue(Page $page, Field $field, $value)
string

Sanitize value for placement on Page object

 
FieldtypeToggle::sleepValue(Page $page, Field $field, $value)
string

Given an 'awake' value, as set by wakeupValue(), convert the value back to a basic type for storage in database.

Additional methods and properties

In addition to the methods and properties above, FieldtypeToggle also inherits the methods and properties of these classes:

API reference based on ProcessWire core version 3.0.261