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--' ExampleForm::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', [], []);Extending this class<?php
/**
* New class description goes here
*
* @author Your Name, 2024-05-03
**/
class NewClassName extends Form {
/**
* Returns HTML for a list of checkboxes, applying name conversions along the way
*
* Uses {@see Fb::checkboxBoolList} to generate the underlying checkbox list
**/
public function checkboxList (array $checkboxes, array $attrs) {
// Method code goes here
}
/**
* 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 function autofillList (string $name, array $attrs, array $options) {
// Method code goes here
}
/**
* Returns HTML for a text field, using {@see Fb::text} to generate the field itself
**/
public function text (string $name, array $attrs) {
// Method code goes here
}
/**
* Returns HTML for a number field, using {@see Fb::number} to generate the field itself
**/
public function number (string $name, array $attrs) {
// Method code goes here
}
/**
* Returns HTML for a bunch of radiobuttons, using {@see Fb::multiradio} to generate the fields
**/
public function multiradio (string $name, array $attrs, array $options) {
// Method code goes here
}
/**
* Returns HTML for a password field, using {@see Fb::password} to generate the field itself
**/
public function password (string $name, array $attrs) {
// Method code goes here
}
/**
* Returns HTML for a money field, using {@see Fb::money} to generate the field itself
**/
public function money (string $name, array $attrs, array $options) {
// Method code goes here
}
/**
* Return content which has been HTML-encoded and wrapped in the form field DIVs
**/
public function out (string $plain) {
// Method code goes here
}
/**
* Returns the first argument
*
* This hacky little method works around the fact that fieldPlain only accepts a method name
**/
protected function passString (string $str) {
// Method code goes here
}
/**
* Return HTML which has been wrapped in the form field DIVs
**/
public function html (string $html) {
// Method code goes here
}
/**
* 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 {@see Form::fieldAuto}
**/
public function __callStatic (string $func, array $args) {
// Method code goes here
}
/**
* 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 function fieldAuto (callable $method, string $name, array $attrs, array $options) {
// Method code goes here
}
/**
* 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--"
**/
public function fieldFieldset (callable $method, string $name, array $attrs, array $options) {
// Method code goes here
}
/**
* Format a field name as per the specification defined by {@see Form::setFieldNameFormat}
**/
protected function convertFieldName (string $name) {
// Method code goes here
}
/**
* 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 function getFieldErrors (string $field_name) {
// Method code goes here
}
/**
* 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--"
**/
public function fieldPlain (callable $method, string $name, array $attrs, array $options) {
// Method code goes here
}
/**
* Convert a full method name (e.g. Sprout\Helpers\Fb::text) into a friendly class name
*
* The classes {@see Fb} and {@see Form} aren't emitted, but all other class names are
**/
protected function fieldMethodClass (string $method) {
// Method code goes here
}
/**
* 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, {@see Text::limitedSubsetHtml} for more details
**/
public function nextFieldDetails (string $label, bool $required, string $helptext) {
// Method code goes here
}
/**
* 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
**/
protected function genId () {
// Method code goes here
}
/**
* Reset the state machine for field values
**/
public function resetField () {
// Method code goes here
}
/**
* Set a format string which will alter the field name prior to being passed to the underlying render method
*
* Formatting is done using {@see 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 function setFieldNameFormat (string $format) {
// Method code goes here
}
/**
* Sets the prefix for generated IDs
**/
public function setFieldIdPrefix (string $prefix) {
// Method code goes here
}
/**
* 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 {@see Form::setData}
* field_errors Field errors, loaded using {@see Form::setErrors}
**/
public function loadFromSession (string $key, mixed $verify_record_id) {
// Method code goes here
}
/**
* 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 {@see Validator::getFieldErrors} method can be used directly as input to this method
**/
public function setErrors (array $errors) {
// Method code goes here
}
/**
* Sets the value for a single field
*
* As form fields are rendered using the {@see Fb} class, this method just sets the data there
**/
public function setFieldValue (array $field, array $value) {
// Method code goes here
}
/**
* Gets the form per-field value for a single field
*
* As form field datas are stored using the {@see Fb} class, this method just gets the data from there
**/
public function getData (string $field) {
// Method code goes here
}
/**
* Set form per-field values for the fields
*
* As form fields are rendered using the {@see Fb} class, this method just sets the data there
**/
public function setData (array $data) {
// Method code goes here
}
}
?>
|
