Cp/Form Service

The Cp/Form Service allows for the creation of Shared Form View data using an object oriented interface.

Note this requires PHP >= 7.1

Usage

The below shows The Cp/Form Service at its simplest; every form can contain multiple groups, which can contain multiple field sets, which can contain multiple fields.

Basic

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

$field_set = $field_group->getFieldSet('First Name');
$field_set->getField('first_name', 'text');

$field_set = $field_group->getFieldSet('Last Name');
$field_set->getField('last_name', 'text');

$form->toArray();

Form Options

$form = ee('CP/Form');
$form->setCpPageTitle('My Custom Form')
    ->asFileUpload()
    ->asTab()
    ->addAlert('custom_alert');

$field_group = $form->getGroup('General Settings');

$field_set = $field_group->getFieldSet('First Name');
$field_set->getField('first_name', 'text');

$field_set = $field_group->getFieldSet('Last Name');
$field_set->getField('last_name', 'text');

$form->toArray();

API Reference

class ExpressionEngine\Library\Cp\Form

This object contains the complete outline for your Shared Form View array. For simple forms, all you’ll have to do is call the Service using EE’s loader, but for more complex Forms, you have quite a few options available.

asTab()

Will output the Form object as a Tabbed format array form.

isTab()

Determines if the Form is setup to be rendered as a Tabbed form

asHeading()

Will output the Form object as a linear array form (the default)

getGroup($group_name)

Will return the Field Group if it exists, or prepare and return a new Field Group. See Field Groups for more details.

removeGroup($group_name)

Removes the specified group from the Form object

toArray()

Returns the entire Cp\Form object into an array compatible with the Shared Form View layer. Note that all child elements are converted to an array as well.

render()

Returns the entire Cp\Form object as a string for use within the Control Panel.

asFileUpload()

Sets the Shared Form View layer to set the form input’s enctype to multipart/form-data

addAlert($alert_name)

Sets the Form to render specific Cp/Alert objects

removeAlert($alert_name)

Removes the specified group from the Form object

getButton($name)

Will return the specified Form\Button object if it exists, or prepare and return a new Button object. See Buttons for more details.

removeButton($name)

Removes the specified Button from the Form object

getHiddenField($name)

Will return the specified Form\Fields\Hidden object if it exists, or prepare and return a new Field object.

removeHiddenField($name)

Removes the specified Hidden Field from the Form object

withActionButton($text, $href, $rel = '')

Will include a custom HTML button with a link in lieu of the top right button of your form.

withOutActionButton()

Will remove the set action button

setCpPageTitle($text)

Sets the string to use for the Page Title within the Control Panel

getCpPageTitle()

Returns the Page title being used

setCpPageTitleAlt($text)

Sets the string to use for the Alternative Page Title within the Control Panel (cp_page_title_alt)

getCpPageTitle()

Returns the Alternative Page title being used (cp_page_title_alt)

setAlertsName($text)

Sets the internal Alerts ID to use specific to this Form (alerts_name)

getAlertsName()

Returns the internal Alerts ID to use specific to this Form (alerts_name)

setBaseUrl($url)

The URL to process the Form (base_url)

getBaseUrl()

Returns the URL (base_url)

A Complete Example

The below includes as many examples and should copy/paste into your project

$form = ee('CP/Form');
$form->asTab();
$form->asFileUpload();
$field_group = $form->getGroup('General Settings');
$field_set = $field_group->getFieldSet('First Name');
$field_set->getField('first_name', 'text')
    ->setDisabled(true)
    ->setValue('Eric');

$field_set = $field_group->getFieldSet('Last Name')->withButton('Click Me');
$field_set->getField('last_name', 'text')
    ->setPlaceholder('Last Name')
    ->setRequired(true);
$form->setCpPageTitle('Hello!');

$field_group = $form->getGroup('Custom Input Example');
$field_set = $field_group->getFieldSet('email');
$field_set->getField('email', 'email')
    ->setPlaceholder('Your Email Address')
    ->setValue('[email protected]')
    ->setRequired(true);

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

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

$field_group = $form->getGroup('Contact details');
$field_set = $field_group->getFieldSet('Address');
$field_set->getField('address1', 'text');
$field_set->getField('address2', 'action_button')->setText('Hello');
$field_set->getField('state', 'dropdown')->withNoResults('Nothing Here', 'fdsa', 'fdsa');

$form->withActionButton('My Action Button', 'https://google.com');
$button = $form->getButton('button_1');
$button->setType('submit')->setText('Submit Button')->setWorking('Submitting...');

$form->getButton('button_2');
$form->removeButton('button_2');

$hidden_field = $form->getHiddenField('my_hidden_field');
$hidden_field->setValue('my_value');

$field_group = $form->getGroup('Table Example');
$field_set = $field_group->getFieldSet('My Table Data');
$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!',
]);

$field_group = $form->getGroup('Filepicker Example');
$field_set = $field_group->getFieldSet('My Filepicker');
$file_picker = $field_set->getField('my_file_picker', 'file-picker');
$file_picker->asImage()->withDir(7)->setValue('{filedir_7}path.jpg');

$field_group = $form->getGroup('Grid Example');
$field_set = $field_group->getFieldSet('My Grid')->withGrid();
$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 ));

$vars = $form->toArray();**

---

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