Form Fields

Every Field Set consists of one or more Fields. The below covers everything about Fields.

Usage

When working with Fields, you’ll always request it from the Field Set object to request it, initially. Once you have it, you’ll decorate it like everything else. For example:

$form = ee('CP/Form');
$field_group = $form->getGroup('General Settings');
$field_set = $field_group->getFieldSet('First Name');

$field = $field_set->getField('first_name', 'text')
    ->setPlaceholder('First Name')
    ->setRequired(true);

The above will attach a text Input field onto the Field Set “First Name”.

Every existing Shared Form View input field is respected as are a couple additions exclusively through the CP/Form layer:

• A simplified and streamlined Grid and Table layer
• Native ExpressionEngine Filepicker
• Custom HTML Inputs

First Party Fields

action_button

class ExpressionEngine\Library\CP\Form\Fields\ActionButton

Adds a “pretty” button style link to your form.

setLink($class)

Returns URL you want to use (link).

getLink()

Returns URL you want to use (link)

setText($text)

The copy to use for the button (text).

getText()

Returns URL you want to use (text)

checkbox

class ExpressionEngine\Library\CP\Form\Fields\Checkbox

Adds a specialized widget for checkbox

dropdown

class ExpressionEngine\Library\CP\Form\Fields\Dropdown

Adds a fancy select input field especially useful for large data sets to choose from.

file

class ExpressionEngine\Library\CP\Form\Fields\File

Adds a traditional file HTML field to your form.

file-picker

class ExpressionEngine\Library\CP\Form\Fields\FilePicker

Adds a File Picker widget to your shared form

withAll()

Sets the allowed directory parameter to any upload location.

withDir($upload_dir)

Sets the specific upload location to use

isAll()

Determines whether an upload location has been set

asAny()

Set the uploaded file type can be any mime type

asImage()

Set the uploaded file type to images only

isImage()

Determines whether the mime type is locked to images only

grid

class ExpressionEngine\Library\CP\Form\Fields\Grid

Allows for a more streamlined implementation of Grid within Shared Forms. Two important differences with this implementation is a simpler API and direct handling of POST values.

Note that the Grid Field inherits from the Table Field; as such there’s really only a single method.

defineRow($row)

Determines whether the mime type is locked to images only

The $row array should be formatted as a simple 2 level, multidimensional, array with each child representing a column and it’s fields. As of now, the Grid Field accommodates select, text, checkbox, file, password, and textarea fields natively.

See the below example for a complete outline.

Example

$grid = $field_set->getField('my_grid_field', 'grid');

$grid->setOptions([
    'field_name' => $grid->getName(),
    'reorder'    => true,
]);

$grid->setColumns([
    'text example' => ['sort' => false],
    'select example' => ['sort' => false],
    'password example' => ['sort' => false],
    'checkbox example' => ['sort' => false],
    'textarea example' => ['sort' => false],
    'upload example' => ['sort' => false],
]);

$options = ['foo' => 'Foo', 'bar' => 'Bar'];
$cols = [
    ['name' => 'foo-text', 'type' => 'text', 'value' => ''],
    ['name' => 'barr-select', 'type' => 'select', 'value' => '', 'choices' => $options],
    ['name' => 'foo-password', 'type' => 'password', 'value' => ''],
    ['name' => 'bar-checkbox', 'type' => 'checkbox', 'value' => 1],
    ['name' => 'foo-textarea', 'type' => 'textarea', 'value' => '', 'cols' => 2, 'rows' => 5],
    ['name' => 'bar-upload', 'type' => 'file', 'value' => '', 'cols' => 2, 'rows' => 5],
];
$grid->defineRow($cols);
$grid->setData([
    ['foo-text' => 'bar', 'barr-select' => 'foo', 'foo-password' => 'fdsa', 'bar-checkbox' => 1, 'foo-textarea' => '', 'bar-upload' => ''],
    ['foo-text' => 'fdsafdsa', 'barr-select' => 'bar', 'foo-password' => 'fdsa', 'bar-checkbox' => true, 'foo-textarea' => '', 'bar-upload' => '']
]);

$grid->setNoResultsText(sprintf(lang('no_found'), lang('table-thing')), 'add');
$grid->setBaseUrl( ee('CP/URL')->make($this->base_url ));

hidden

class ExpressionEngine\Library\CP\Form\Fields\Hidden

Adds a hidden field to your form

html

class ExpressionEngine\Library\CP\Form\Fields\Html

Allows for putting raw (unformatted) HTML inside your form

setContent($content)

Sets the specific upload location to use

getContent()

Returns the content (empty string by default)

multiselect

class ExpressionEngine\Library\CP\Form\Fields\Multiselect

Deploys a series of select input fields together

addDropdown($name, $value, $label, $options)

Adds a single Dropdown element to your Field

removeDropdown($name)

Returns the content (empty string by default)

password

class ExpressionEngine\Library\CP\Form\Fields\Password

Adds your run of the mill password input field wrapped in magic that puts an eye next to it.

radio

class ExpressionEngine\Library\CP\Form\Fields\Radio

This behaves just like checkbox with the exception of being scalar so uses a scalar for the value. See checkbox for details.

select

class ExpressionEngine\Library\CP\Form\Fields\Select

Adds a traditional select input field to your form.

short-text

class ExpressionEngine\Library\CP\Form\Fields\ShortText

Adds a small input HTML field wrapped in a div with flex-input as the class. Useful for stacking fields horizontally.

setLabel($label)

Will place a bold string under the field for users to clickety clackity on

getLabel()

Returns the label (empty string by default)

slider

class ExpressionEngine\Library\CP\Form\Fields\Slider

Puts a slider widget into your form

setMin($min)

The lowest value in the range of permitted values

getMin()

Returns the minimum value to allow

setMax($max)

The greatest value in the range of permitted values

getMax()

Returns the maximum value to allow

setStep($step)

Specifies the granularity that the value must adhere to (if any is used, no stepping is implied, and any value is allowed (barring other constraints, such as min and max)

getStep()

Returns the step value

setUnit($unit)

The symbol your data can best be represented by (defaults to %)

getUnit()

Returns the unit value

table

class ExpressionEngine\Library\CP\Form\Fields\Table

Allows for a more streamlined implementation of tables within Shared Forms

setColumns($cols)

Sets the columns and options for the Table. Use this to outline how your columns are rendered and prepared.

getColumns()

Returns the column options

setOptions($cols)

Sets the table options

getOptions()

Returns the table options

setNoResultsText($text, $action_text, $action_link, $external)

Sets what the table displays if there isn’t any data provided to it

getNoResultsText()

Returns the no results details as an array

setData($data)

Sets the table row data as an array. Note that this be a multidimensional array with each child element representing a column and each parent a row

getData()

Returns the table row data

addRow($row)

Adds a single row to the Table

setBaseUrl($url)

Sets the URL parameters will be based on

getBaseUrl()

Returns the ExpressionEngine\Library\CP\Url object

Example

$table = $field_set->getField('my_table', 'table');

$table->setOptions([
    'lang_cols' => true,
    'class' => 'product_channels'
]);

$table->setColumns([
    'details' => ['sort' => false],
    'value' => ['sort' => false],
]);

$table->setNoResultsText(sprintf(lang('no_found'), lang('product_channels')));
$table->setBaseUrl( ee('CP/URL')->make($this->base_url ));
$data = [];
$data[] = [
    'Hello',
    'You',
];

$table->setData($data);
$table->addRow([
    'No, Hello',
    'To You!',
]);

text

class ExpressionEngine\Library\CP\Form\Fields\Text

Adds a traditional input HTML field

textarea

class ExpressionEngine\Library\CP\Form\Fields\Textarea

Adds a full textarea input field

setKillPipes($kill)

Flag to replace any ¦ delimiters with new lines (\n)

getKillPipes()

Returns the minimum value to allow

setCols($cols)

Sets how many columns to set the field to use

getCols()

Returns the number of columns

setRows($rows)

Sets how many rows to set the field to use

getRows()

Returns the number of rows

toggle

class ExpressionEngine\Library\CP\Form\Fields\Toggle

Adds a Toggle binary toggle

yes_no

class ExpressionEngine\Library\CP\Form\Fields\YesNo

Adds a Toggle control that returns either y or n respectively.

The Input Field

If you want to use a native HTML5 input that is not already a Field, you can do so quite easily. IF a Field is requested that doesn’t exist, a Field of the Input variety will be provided. The Input Field provides a single custom method that will allow you to craft custom HTML5 input elements.

params($params)

A key=>value array of parameters to be chained into a string internally

Example

Here’s a simple example building both number and color Input Fields.

$field_set = $field_group->getFieldSet('color');
$field_set->getField('my_color_field', 'color')->setValue('#C86565');

$field_set = $field_group->getFieldSet('number');
$field_set->getField('my_number_field', 'number')->params(['min' => 100, 'max' => 1000])->setRequired(true);

Field API Reference

class ExpressionEngine\Library\CP\Form\Field

All input fields are based on the Field object. Note that while every Field will have the below methods available, whether they’re respected by the Shared Form View layer is a different matter.

toArray()

Returns the entire CP\Form\Field object into an array.

getName()

Returns the name used upon creation for the Field.

setClass($class)

The class property to apply to the Field (class).

getClass()

Returns the class property (class)

withMarginTop()

The class margin_top is added to your input element.

withOutMarginTop()

Removes the margin_top from your input

withMarginLeft()

The class margin_left is added to your input element.

withOutMarginLeft()

Removes the margin_left from your input

setNote($note)

The string you want to use for your Note (note).

getNote()

Returns the note string (note)

setAttrs($attrs)

Any custom input parameters you want to attach to your Field (attrs).

getAttrs()

Returns the attributes string (attrs)

setDisabled($disabled)

Whether the Field should be editable (disabled).

getDisabled()

Whether the Field is disabled (disabled)

setValue($value)

The value to use for the “value” parameter (value).

getValue()

The value to use on the Field (value)

setGroup($group)

The group you want to relate this Field to (group).

getGroup()

The group this Field is related to (group)

setGroupToggle($group_toggle)

The group toggle you want to relate this Field to (group_toggle).

getGroupToggle()

The group toggle this Field controls (group_toggle)

setRequired($required)

Whether the field can accept input/editing (required).

getRequired()

Whether this Field is required (required)

setPlaceholder($required)

The string to use for the input “placeholder” attribute (placeholder).

getPlaceholder()

Whether this Field is required (placeholder)

OptionsField API Reference

class ExpressionEngine\Library\CP\Form\OptionsField

Input Fields that allow for multiple options or set input parameters are based on the OptionsField abstract. Note that OptionsField extends from Field so you’ll also have access to those parent methods, as well.

withNoResults($text, $link_text, $link_href)

Used to define quick links when choices are empty.

withOutNoResults()

Will remove the set no results details

setChoices($value)

A simple key=>value array pair to populate options (choices).

getChoices()

The value to use on the Field (choices)

setEncode($encode)

Whether to format text so that it can be safely placed in a form field in the event it has HTML tags (encode).

getEncode()

Whether this Field is encoded (encode)

setDisabledChoices($disabled_choices)

A list of keys used in the options array to prevent selection (disabled_choices).

getDisabledChoices()

The set disabled choices (disabled_choices)

setEmptyText($disabled_choices)

The text to display if there are no options (empty_text).

getEmptyText()

The set text to display (empty_text)

---

ExpressionEngine 7 Docs
©2002–2024 Packet Tide,LLC. Edit this page