# Base Field Manager
FIELD API EXTEND FIELDSThe Fluent Forms BaseFieldManager Functions provides developers with a future-proof way to add new form fields easily.
The API Functions are automatically included when Fluent Forms Booted, and they will be available anytime within init hook. The BaseFieldManager class is located at in fluentform/app/Services/FormBuilder/BaseFieldManager.php (opens new window).
Please check out the GitHub file to get more information.
Notice: Please do not initiate this class directly. You should extend this class to add anew form field.
# Example Implementation
# Methods
# getComponent()
/*
* Implement your method to describe the full element
* return $component array
*/
abstract function getComponent()
2
3
4
5
This is an abstract class that you have to implement in your own class. From this method you have to return the full attributes of the element which will be available for settings in the form editor as well as in your render() function.
Here is an example of a custom element (Advanced Phone Field) structure which is available in our pro version of Fluent Forms
function getComponent()
{
return [
'index' => 15, // The priority of your element
'element' => $this->key, // this is the unique identifier.
'attributes' => [
'name' => $this->key, // initial name of the input field
'class' => '', // Custom element class holder
'value' => '', // Default Value holder
'type' => 'tel', // type of your element eg: text/number/email/tel
'placeholder' => __('Mobile Number', 'fluentformpro') // Default Placeholder
],
'settings' => [
'container_class' => '',
'placeholder' => '',
'label' => $this->title,
'label_placement' => '',
'help_message' => '',
'admin_field_label' => '',
'validation_rules' => [
'required' => [
'value' => false,
'message' => __('This field is required', 'fluentformpro'),
],
'valid_phone_number' => [
'value' => false,
'message' => __('Phone number is not valid', 'fluentformpro')
]
],
'conditional_logics' => []
],
'editor_options' => [
'title' => $this->title . ' Field',
'icon_class' => 'el-icon-phone-outline', // icon of the form in editor
'template' => 'inputText' // The template that will show in editor preview
],
];
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
The code is already self-explanatory. But you have to keep the structure as same as the example. The array need to have the following keys:
- index
- element
- attributes (will be used for rendering in editor and frontend)
- name
- class
- value
- type
- placeholder
- settings
- label
- container_class
- label_placement
- help_message
- admin_field_label
- validation_rules
- conditional_logics
- editor_options (For Editor)
- title
- icon_class
- template (View Available Templates (opens new window))
Please check our other element implementations in fluentformpro/src/Components folder to get an idea about the available attributes.
To check all the existing get component data structure please check this file (opens new window). That file contains all free and some pro version data attributes implementation.
# render($data, $form)
/*
* Implement render html for your form element. You have to print your element html
* @param: $element array - Contain the total element with attributes, settings etc
* @param: $form object - Form Object of the current form rendering in that time.
* @return void
*/
abstract function render($element, $form);
2
3
4
5
6
7
You have to implement this method and print the final html for your custom element. Please check other implementations in pro versions fluentformpro/src/Components folder. The DOM need to be symmetric, and you must have to use the parent class function to generate the DOM's to make the conditional logic/error messages work.
Please check the all element render(compile()) method in these files.
# getGeneralEditorElements()
This is an important method that you have to implement when implementing your own element class. This method will return what settings will show in the general settings of your form element.
For example:
public function getGeneralEditorElements()
{
return [
'label',
'admin_field_label',
'placeholder',
'value',
'label_placement',
'validation_rules',
];
}
2
3
4
5
6
7
8
9
10
11
Please note that, These keys need to be matched with either your component’s settings or attributes keys.
# getAdvancedEditorElements()
This is an important method to that you have to implement when implementing your own element class. This method will return what settings will show in the advanced settings of your form element. By default, it returns the following
For example:
public function getAdvancedEditorElements()
{
return [
'name',
'help_message',
'container_class',
'class',
'conditional_logics',
];
}
2
3
4
5
6
7
8
9
10
You should implement this method if you want to add or remove any settings.
Please note that, These keys need to be matched with either your component’s settings or attributes keys.
# Element Settings UI components for EditorElements
There has 69 UI components for making any type of settings ui for your element. You can even implement your own by implementing generalEditorElement and advancedEditorElement method. Please check the source code or phone field element in pro version.
Where to find the built-in UI components: Please check in the GitHub source file here (opens new window)
# Implementing this class
Create a php class and then extend this class. Here is the example where we can use they must use methods
class MyAwesomeFFElement extends \FluentForm\App\Services\FormBuilder\BaseFieldManager
{
public function __construct()
{
parent::__construct(
'key',
'Element title',
['tag1', 'tag2', 'tag3'],
'general' // where to push general/advanced
);
}
function getComponent()
{
return []; // return your element structure
}
public function getGeneralEditorElements()
{
return []; // return your general settings keys
}
public function getAdvancedEditorElements()
{
return []; // return your advanced settings keys
}
public function render($data, $form)
{
// print your valid html for this element
}
}
/*
* Finally initialize the class
*/
add_action('fluentform/loaded', function () {
new MyAwesomeFFElement();
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# Further read
# Validate data of inputed from frontend
If you want to validate user input data for your form submission you have implement a filter hook
add_filter('fluentform/validate_input_item_{YOUR_ELEMENT_KEY}', function ($errorMessage, $field, $formData, $fields, $form) {
$fieldName = $field['name'];
if (empty($formData[$fieldName])) {
return $errorMessage;
}
$value = $formData[$fieldName]; // This is the user input value
/*
* You can validate this value and return $errorMessage
*/
return [$errorMessage];
}, 10, 5);
2
3
4
5
6
7
8
9
10
11
12
13
14
Learn more about this validation here
# Transforming Input Data in Entries/Emails
Maybe you collected the data as array or key of any dynamic data, and you need to transform that data to anywhere that is viewable at admin panel entries/email/3rd party integrations.
/**
* @param $response string|array|number|null - Original input from form submission
* @param $field array - the form field component array
* @param $form_id - form id
* @param $isHtml - For HTML render
* @return string
*/
add_filter('fluentform/response_render_{element_key}', function($response, $field, $form_id, $isHtml) {
// $response is the original input from your user
// you can now alter the $response and return
return $response;
}, 10, 4);
2
3
4
5
6
7
8
9
10
11
12
# All Together
Your ideal implementation will look like this if you want to use both custom validation and custom response render.
class MyAwesomeFFElement extends \FluentForm\App\Services\FormBuilder\BaseFieldManager
{
public function __construct()
{
parent::__construct(
'myAwesome_ff_element_key',
'Element title',
['tag1', 'tag2', 'tag3'],
'general' // where to push general/advanced
);
add_filter('fluentform/response_render_' . $this->key, array($this, 'renderResponse'), 10, 4);
add_filter('fluentform/validate_input_item_' . $this->key, array($this, 'validateInput'), 10, 5);
}
function getComponent()
{
return []; // return your element structure
}
public function getGeneralEditorElements()
{
return []; // return your general settings keys
}
public function getAdvancedEditorElements()
{
return []; // return your advanced settings keys
}
public function render($data, $form)
{
// print your valid html for this element
}
/**
* @param $response string|array|number|null - Original input from form submission
* @param $field array - the form field component array
* @param $form_id - form id
* @param $isHtml - For HTML
* @return string
*/
public function renderResponse($response, $field, $form_id, $isHtml)
{
// $response is the original input from your user
// you can now alter the $response and return
return $response;
}
public function validateInput($errorMessage, $field, $formData, $fields, $form)
{
$fieldName = $field['name'];
if (empty($formData[$fieldName])) {
return $errorMessage;
}
$value = $formData[$fieldName]; // This is the user input value
/*
* You can validate this value and return $errorMessage
*/
return [$errorMessage];
}
}
/*
* Finally initialize the class
*/
add_action('fluentform/loaded', function () {
new MyAwesomeFFElement();
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
# Final Note
It’s highly recommended to explore our source files and try to understand the design. Once you get if it’s very easy to implement your own custom input elements. Also, please check our a step by step your custom new field creation guide here How to Create Your Own Custom Field in Fluentforms (opens new window).
If you have any question please feel free to reach at our support team (opens new window) or ask questions in our facebook community group (opens new window)