Form class - Documentation for SproutCMS

Info Page:

Page options:

class Form

Helper functions for outputting form elements.

Wraps form fields (e.g. from Fb) with additional HTML.

Most wrapping will done using the __callStatic method which actually just calls Form::fieldAuto.
That method uses reflection to look for a custom docblock tag, @wrap-in-fieldset.
If that docblock tag is found, the field is wrapped in Form::fieldFieldset
If that docblock tag is not found (the most common case), the field is wrapped in Form::fieldPlain

If the field being wrapped isn't in the Fb helper, the methods fieldAuto, fieldPlain, and fieldFieldset
can be invoked directly.

The outermost wrapper DIV around the field has a class of "field-element".
Additional classes are also added:
 - The method and class name, in the format 'field-element--id-<name>'
 - If an "id" attribute is set, in the format 'field-element--id-<id>'
 - If the field is required, 'field-element--required'
 - If the field is disabled, 'field-element--disabled'
 - If the field has an error, 'field-element--error'
 - One or more custom classes can be specified using the attribute "-wrapper-class".
   Each (array or space separated) class is prefixed with 'field-element--'

File: /sprout/Helpers/Form.php
Namespace: Sprout\Helpers

Example

Form::setData($data);
Form::setErrors($errors);
 
Form::nextFieldDetails('First name', true);
echo Form::text('first_name');
 
Form::nextFieldDetails('Email', true, 'Please enter your email address');
echo Form::email('email', [], ['-wrapper-class' => 'small']);
 
Form::nextFieldDetails('Phone', false, 'Enter a phone number using the unique UI');
echo Form::fieldPlain('SproutModules\Someone\CustomModule\Helpers\FbHack::phone', 'phone', [], []);

Variables

Name	Visibility	Description
`$errors`	(static)
`$id_prefix`	(static)
`$name_format`	(static)
`$next_helptext`	(static)
`$next_label`	(static)
`$next_required`	(static)

Functions

Name	Visibility	Description
__callStatic	public (static)	Auto-wrapper around Fb methods
autofillList	public (static)	Returns HTML for an auto-complete list of records
checkboxList	public (static)	Returns HTML for a list of checkboxes, applying name conversions along the way
convertFieldName	protected (static)	Format a field name as per the specification defined by Form::setFieldNameFormat
fieldAuto	public (static)	Return HTML for a field, with the wrapping HTML detected automatically.
fieldFieldset	public (static)	Return HTML for a field wrapped in a FIELDSET
fieldMethodClass	protected (static)	Convert a full method name (e.g. Sprout\Helpers\Fb::text) into a friendly class name
fieldPlain	public (static)	Return HTML for a 'plain' field, i.e. one which doesn't require a FIELDSET wrapped around it.
genId	protected (static)	Generate a unique id which should be stable across calls to this URL
getData	public (static)	Gets the form per-field value for a single field
getFieldErrors	public (static)	Return the errors for a given field
html	public (static)	Return HTML which has been wrapped in the form field DIVs
loadFromSession	public (static)	Load data and errors from the session, with optional record id validation
money	public (static)	Returns HTML for a money field, using Fb::money to generate the field itself
multiradio	public (static)	Returns HTML for a bunch of radiobuttons, using Fb::multiradio to generate the fields
nextFieldDetails	public (static)	Set the details for the next field which will be outputted.
number	public (static)	Returns HTML for a number field, using Fb::number to generate the field itself
out	public (static)	Return content which has been HTML-encoded and wrapped in the form field DIVs
passString	protected (static)	Returns the first argument
password	public (static)	Returns HTML for a password field, using Fb::password to generate the field itself
resetField	public (static)	Reset the state machine for field values
setData	public (static)	Set form per-field values for the fields
setErrors	public (static)	Set per-field error messages to display
setFieldIdPrefix	public (static)	Sets the prefix for generated IDs
setFieldNameFormat	public (static)	Set a format string which will alter the field name prior to being passed to the underlying render method
setFieldValue	public (static)	Sets the value for a single field
text	public (static)	Returns HTML for a text field, using Fb::text to generate the field itself

public __callStatic

string Form::__callStatic ( string $func , array $args );

Auto-wrapper around Fb methods

Will wrap the Fb method with the same name as the called method, e.g. Form::datepicker wraps Fb::datepicker
Wrapping is done using Form::fieldAuto

public autofillList

string Form::autofillList ( string $name , array $attrs , array $options );

Returns HTML for an auto-complete list of records

The form data for this field should be an array of arrays with at least the following keys:
[
    'id' => record ID,
    'value' => title text visible in the list item,
    'orderkey' => ordinal value for record ordering
]

public checkboxList

string Form::checkboxList ( array $checkboxes , array $attrs );

Returns HTML for a list of checkboxes, applying name conversions along the way

Uses Fb::checkboxBoolList to generate the underlying checkbox list

protected convertFieldName

string Form::convertFieldName ( string $name );

Format a field name as per the specification defined by Form::setFieldNameFormat

public fieldAuto

string Form::fieldAuto ( callable $method , string $name , array $attrs , array $options );

Return HTML for a field, with the wrapping HTML detected automatically.

To enable fieldset wrapping, add the docblock tag @wrap-in-fieldset to the field generation method

public fieldFieldset

string Form::fieldFieldset ( callable $method , string $name , array $attrs , array $options );

Return HTML for a field wrapped in a FIELDSET

The main wrapping DIV will contain additional classes if the field is required, disabled or has an error.
A class is also output for hte field method name (if the name contains "Sprout\Helpers\Fb::" this is removed)
If the field has an explicit ID set, that will be added as a class on the wrapper too.

The special attribute "-wrapper-class" can be used to add classes to the wrapper DIV.
Multiple classes can be specified, space separated.
These classes will be prefixed with "field-element--"

protected fieldMethodClass

string Form::fieldMethodClass ( string $method );

Convert a full method name (e.g. Sprout\Helpers\Fb::text) into a friendly class name

The classes Fb and Form aren't emitted, but all other class names are

public fieldPlain

string Form::fieldPlain ( callable $method , string $name , array $attrs , array $options );

Return HTML for a 'plain' field, i.e. one which doesn't require a FIELDSET wrapped around it.

The main wrapping DIV will contain additional classes if the field is required, disabled or has an error.
A class is also output for the field method name (if the name contains "Sprout\Helpers\Fb::" this is removed)
If the field has an explicit ID set, that will be added as a class on the wrapper too.

The special attribute "-wrapper-class" can be used to add classes to the wrapper DIV.
Multiple classes can be specified, space separated.
These classes will be prefixed with "field-element--"

protected genId

string Form::genId ( );

Generate a unique id which should be stable across calls to this URL
as long as the number and order of fields on the page remains the same

public getData

unknown Form::getData ( string $field );

Gets the form per-field value for a single field

As form field datas are stored using the Fb class, this method just gets the data from there

public getFieldErrors

NULL|array Form::getFieldErrors ( string $field_name );

Return the errors for a given field

Supports nested error arrays; If $field_name is something like member[5][test] then the error
will be read from self::$errors['member']['5']['test']

public html

string Form::html ( string $html );

Return HTML which has been wrapped in the form field DIVs

public loadFromSession

null|array Form::loadFromSession ( string $key [, mixed $verify_record_id ] );

Load data and errors from the session, with optional record id validation

Expected session keys:
    record_id       Checked against $verify_record_id, session data is thrown away in case of mismatch
    field_values    Field data, loaded using Form::setData
    field_errors    Field errors, loaded using Form::setErrors

public money

string Form::money ( string $name , array $attrs , array $options );

Returns HTML for a money field, using Fb::money to generate the field itself

public multiradio

string Form::multiradio ( string $name , array $attrs , array $options );

Returns HTML for a bunch of radiobuttons, using Fb::multiradio to generate the fields

public nextFieldDetails

void Form::nextFieldDetails ( string $label , bool $required [, string $helptext ] );

Set the details for the next field which will be outputted.

After returning a field, these values will be cleared from the state machine

Both the label and helptext support a subset of HTML, Text::limitedSubsetHtml for more details

public number

string Form::number ( string $name , array $attrs );

Returns HTML for a number field, using Fb::number to generate the field itself

public out

string Form::out ( string $plain );

Return content which has been HTML-encoded and wrapped in the form field DIVs

protected passString

string Form::passString ( string $str );

Returns the first argument

This hacky little method works around the fact that fieldPlain only accepts a method name

public password

string Form::password ( string $name , array $attrs );

Returns HTML for a password field, using Fb::password to generate the field itself

public resetField

void Form::resetField ( );

Reset the state machine for field values

public setData

void Form::setData ( array $data );

Set form per-field values for the fields

As form fields are rendered using the Fb class, this method just sets the data there

public setErrors

void Form::setErrors ( array $errors );

Set per-field error messages to display

A given field can have either a single error message or an array of errors
The output from the Validator::getFieldErrors method can be used directly as input to this method

public setFieldIdPrefix

void Form::setFieldIdPrefix ( string $prefix );

Sets the prefix for generated IDs

public setFieldNameFormat

void Form::setFieldNameFormat ( string $format );

Set a format string which will alter the field name prior to being passed to the underlying render method

Formatting is done using sprintf
A single parameter is provided to the sprintf() call, the field name
The default format does no transformation, i.e. the string '%s'
This parameter persists across multiple form fields

public setFieldValue

void Form::setFieldValue ( array $field , array $value );

Sets the value for a single field

As form fields are rendered using the Fb class, this method just sets the data there

public text

string Form::text ( string $name , array $attrs );

Returns HTML for a text field, using Fb::text to generate the field itself

SproutCMS

Search documentation