FormBuilder: Processor

The FormBuilderProcessor class handles the rendering and processing of forms for Form Builder.

This class also contains the most commonly hooked methods in FormBuilder. Please note that this is a class you typically wouldn't call methods from. Instead, most interactions with this class are by hooking its methods. 

$forms->addHook('FormBuilderProcessor::methodName', function(HookEvent $e) {
  $pro = $event->object; // get FormBuilderProcessor
  // ...hook code...
});

// Example
$forms->addHookBefore('FormBuilderProcessor::renderReady', function(HookEvent $event) {
  $pro = $event->object; // FormBuilderProcessor instance
  $form = $pro->getInputfieldForm();
  if($pro->formName == 'foo') {
    // do something for form named "foo"
  } else if($pro->formName == 'bar-baz') {
    // do something else for form named "bar-baz"
  }
});

Where to place FormBuilder hooks?

Hooks can be added anywhere before a form is rendered, for instance in a template file. But depending on the embed method and version, these are common locations:

FileDescription
/site/ready.phpWorks anywhere and in any version
/site/templates/FormBuilder/hooks.phpRequires FormBuilder 0.5.7 or newer
/site/templates/FormBuilder/hooks-formName.phpRequires FormBuilder 0.5.7 and newer
/site/templates/admin.phpUseful if hooks needed in admin only, works in any version
/site/templates/_init.phpWorks only if already using an _init.php, hooks affect front-end only
/site/templates/form-builder.phpPlacing hooks at the top of this file targets just embed methods A and B
/site/templates/form-builder.incThe original FormBuilder hooks file, supported by all versions

Using the hooks.php or hooks-formName.php (replacing formName with actual form name) is preferable when available, as they are loaded only when a form will be rendered or processed.

Processor plugin modules

You can use or create FormBuilderProcessorAction modules to automatically plug-in to any part of the form life cycle. This is ideal if you want to add hook-like functionality that can easily be shared, configured and enabled/disabled on a per-form basis.

Click any linked item for full usage details and examples. Hookable methods are indicated with the icon. In addition to those shown below, the FormBuilderProcessor class also inherits all the methods and properties of: WireData and Wire.

Show $var?     Show args?       Only hookable?    

Entries

NameReturnSummary 
$processor->addEntryReady(array $data, InputfieldForm $form)
array

Hook called when new entry is about to be added

$processor->addedEntry(array $data, InputfieldForm $form)
array

Hook called after a new entry has been added

$processor->entries()
FormBuilderEntries

Get the FormBuilderEntries object for the current form

 
$processor->formToEntry(InputfieldForm $form)
array

Converts the submitted InputfieldForm object to an entry data array

$processor->getEntry()
array null

Get the current form entry, or null if not present

 
$processor->getEntryID()
int

Get the current entry ID, or 0 if not present

 
$processor->loadEntry($entryID)
InputfieldForm

Load entry by ID or name and populate to form

 
$processor->populate(array $data)
InputfieldForm

Populate the form with the key=value data (or form entry) given in the array

$processor->saveEntry(array $data)
int

Save or update a form entry

$processor->setEntry(array $data)
None

Set current entry data

 
$processor->updateEntryReady(array $data, InputfieldForm $form)
array

Hook called when an existing entry is about to be updated

$processor->updatedEntry(array $data, InputfieldForm $form)
array

Hook called when an existing entry has been added

Pages

NameReturnSummary 
$processor->allowSavePageField(Page $page, string $pageFieldName, string $formFieldName, string $value, array $entry)
bool

Returns true if given value should be saved, false if not (for hooks)

$processor->getSavePage()
NullPage Page

Get page that was saved

 
$processor->savePage(array $data)
Page null

Save the form entry to a Page

$processor->savePageAdjustName bool int Adjust page name as needed to ensure it is unique?
DEFAULT: true		 
$processor->savePageCheckName(Page $page)
bool

Check and update page name as needed for uniqueness (for hooks)

$processor->savePageDone(Page $page, array $data, bool $isNew, $onlyFields)
array

Hook called right after a page is saved

$processor->savePageFields array array of [ 'processwire_field_id' => 'form_field_name' ] to map page fields to form fields  
$processor->savePageFileField(Page $page, Field $field, array $filenames, string $formFieldName)
int

Save an individual files field to a Page (for hooks)

$processor->savePageInit(array $data, $status, $onlyFields)
array

Get settings for saving a page (for hooks)

$processor->savePageParent string ID of parent page for newly created pages  
$processor->savePageReady(Page $page, array $data)
None

Hook called right before a Page is about to be saved

$processor->savePageStatus int status of saved page (0 = don't save page now)  
$processor->savePageSubfields string Newline separated string in format: form_field_name=page_field_name.subfield  
$processor->savePageTemplate string Name of template for newly created pages  

Email

NameReturnSummary 
$processor->emailForm(InputfieldForm $form, array $data)
bool int

Email the form result to the administrator(s)

$processor->emailFormPopulateSkipFields(FormBuilderEmail $email, InputfieldForm $form)
None

Hookable method for populating fields that should be skipped in an email

$processor->emailFormReady(InputfieldForm $form, FormBuilderEmail $email)
bool

Hook called before email is sent to administrator

$processor->emailFrom string Email address (or field name where it resides) to use as the reply-to address for the email.  
$processor->emailFrom2 string Email FROM address, if different the one specified in module settings and reply-to address.  
$processor->emailFromName string Email from name  
$processor->emailSubject string subject of email that gets sent  
$processor->emailTo string Email address to send form submissions to, may also be multiple (1 per line) or conditional (1 condition per line)  
$processor->mailer string Name of WireMail module to use for sending email, 'WireMail' for native PHP mail(), or blank for auto-detect.  

Auto responder

NameReturnSummary 
$processor->emailFormResponder(InputfieldForm $form, array $data)
bool

Email the form result to the sender (auto-responder)

$processor->emailFormResponderReady(InputfieldForm $form, FormBuilderEmail $email)
bool

Hook called before email is sent to autoresponder, see details for example

$processor->responderBody string Body for the responder email  
$processor->responderFrom string Email address that the responder email should be from  
$processor->responderFromName string Name responder should be from  
$processor->responderReplyTo string Responder reply-to address  
$processor->responderSubject string Subject line for the responder email  
$processor->responderTo string field name (not email address) that WILL contain the submittor's email address (where the responder should be sent). CSV string for multiple.  

Spam

NameReturnSummary 
$processor->akismet string CSV string containing field names of: "name,email,content" (in that order)  
$processor->honeypot string array name of field that, when populated, invalidates the form submission (or array of them)  
$processor->isSpam()
bool string

Returns name of triggered spam filter when entry detected as spam

 
$processor->processInputIsSpam(InputfieldForm $form, bool $processed)
string

Does given processed form contain spam?

$processor->processInputSpammed(InputfieldForm $form, string $spamType)
None

Hook called when processInput fails due to being spammed

$processor->spamFlags int Spam flags  
$processor->spamTimer int Time required between render and submit for form to be considered valid  
$processor->spamWords array Keywords that flag a form submission as spam.  
$processor->turingTest array array containing list of field names and required answers  

Other actions

NameReturnSummary 
$processor->action2 string URL to send duplicate submission to  
$processor->action2_add array array of name=value to add to duplicate submission  
$processor->action2_remove array array of field names to remove from duplicate submission  
$processor->action2_rename array array of field names rename before duplicate submission  
$processor->googleSheetsResponseField string Name of field to poulate with Google Sheets response (which indicates row and column)  
$processor->googleSpreadsheetFields array  
$processor->googleSpreadsheetUrl string  
$processor->postAction2(array $data)
bool

Post a duplicate copy of the form submission/entry to another URL

$processor->postAction2Ready(WireHttp $http, array $data, string $method, string $url, array $headers)
bool string

Called right before we send a duplicate copy to another URL

$processor->saveGoogleSheets(InputfieldForm $form, array $data)
bool

Save to Google Sheets

$processor->saveGoogleSheetsReady(GoogleSheets $sheets, array $row, array $data)
array

Hook called before spreadsheet row saved, can optionally modify $event->return (spreadsheet row)

Output

NameReturnSummary 
$processor->appendMarkup(string $markup)
None

Add markup to append to the form

 
$processor->dupMessage string message to display when form is already submitted / duplicate submission  
$processor->errorMessage string message to display when a form error occurred  
$processor->renderError(string $error)
string

Render an error message into markup

$processor->renderSuccess(string $message)
string

Render the given success message for output

$processor->renderSuccessMessage(string $message)
string

Render a success message

$processor->renderSuccessRedirect(string $url)
string

Render a success redirect

$processor->submitText string text that appears on the submit button  
$processor->successMessage string message to display on successful form submission, assuming no successUrl was set  
$processor->successUrl string URL to redirect to on successful form submission  

Success

NameReturnSummary 
$processor->formSubmitSuccess(InputfieldForm $form)
None

Called upon successful form submission

$processor->renderSuccess(string $message)
string

Render the given success message for output

$processor->renderSuccessMessage(string $message)
string

Render a success message

$processor->renderSuccessRedirect(string $url)
string

Render a success redirect

$processor->successMessage string message to display on successful form submission, assuming no successUrl was set  
$processor->successUrl string URL to redirect to on successful form submission  

Errors

NameReturnSummary 
$processor->addError(string $text)
None

Add an error message that is shown to the user

 
$processor->addWarning(string $text)
None

Add a warning that can be shown to user but does not prevent form submission

 
$processor->adminError(string $text)
None

Add an error message that is ony shown if user has form-builder permission

 
$processor->clearErrors()
None

Clear all errors and warnings

 
$processor->errorMessage string message to display when a form error occurred  
$processor->formSubmitError(InputfieldForm $form, array $errors)
None

Called upon a form submission error, for hooks to listen to.

$processor->formSubmitInvalid(InputfieldForm $form, array $errors)
None

Called when an invalid form submission is received that prevented it from being processed

$processor->getErrors()
array

Return an array of errors that occurred (strings)

 
$processor->getWarnings()
array

Return an array of warnings that occurred (strings)

 
$processor->hasErrors()
bool

Are there any errors present on form or in this processor?

 
$processor->renderError(string $error)
string

Render an error message into markup

$processor->renderErrors()
string

Render the given error messages for output

$processor->renderErrorsReady(array $errors)
array

Called when errors about to be rendered

Submit

NameReturnSummary 
$processor->getSubmitType()
bool int null

Get the form submit type

 
$processor->getValues()
array

Get an array of all values from this form

 
$processor->isSpam()
bool string

Returns name of triggered spam filter when entry detected as spam

 
$processor->isSubmitted()
bool

Was the form successfully submitted? (for public API)

 
$processor->setSubmitType($submitType)
None

Set the form submit type

 

Settings

NameReturnSummary 
$processor->allowPreset bool allow form field values to be pre-set from GET variables?  
$processor->formName string name of the form  
$processor->framework string Name of form framework to use  
$processor->id int Form ID number  
$processor->pluginActions array Array of FormBuilderProcessorAction module names used as plugins to add form processing actions  
$processor->saveFlags int Flags for saving form submission
DEFAULT: self::saveFlagsDB		 
$processor->showHidden bool Show input[type=hidden] as type=text instead? Option may only be modified in construct $options.
DEFAULT: false		 
$processor->skipSessionKey bool Require a unique session key for each form submission (for security)  
$processor->useCookies bool Remember input values?  
$processor->validateNumFields bool Validate quantity of fields present in form as part of the _submitKey?  

Save flags

Constants used to populate the $saveFlags property, which dictates what actions to take with submitted forms. There can be multiple saveFlags so they should be applied in bitwise fashion.

NameReturnSummary 
FormBuilderProcessor::saveFlagAction2 const4Used when form entries should have a duplicate copy sent to a 3rd party service 
FormBuilderProcessor::saveFlagDB const1Used when form entries should be saved to database 
FormBuilderProcessor::saveFlagEmail const2Used when form entries should be sent via email to administrator 
FormBuilderProcessor::saveFlagExternal const16Used when the form should submit somewhere else (rendering all other save options invalid) 
FormBuilderProcessor::saveFlagFilterSpam const32Used when form submissions should be screened for spam 
FormBuilderProcessor::saveFlagGoogleSheets const128Used when form submissions should also save to Google Sheets 
FormBuilderProcessor::saveFlagPage const8Used when entries should be saved to new pages 
FormBuilderProcessor::saveFlagResponder const64Used when form submissions should include an auto-responder email 
FormBuilderProcessor::saveFlagsLabels()
array string

Get array (or csv string) of text labels for given saveFlags

 

Form flags

Constants used to populate the $formFlags property, which maintains form toggle settings. There can be multiple saveFlags so they should be applied in bitwise fashion.

NameReturnSummary 
FormBuilderProcessor::formFlagDisabled const4Used when form is disabled for accepting new entries 
FormBuilderProcessor::formFlagEditLinks const1024Used when edit links should be shown in form preview 0.5.7+  
FormBuilderProcessor::formFlagEmailFiles const256Used when uploaded files should be included as email attachments 
FormBuilderProcessor::formFlagEmailSubjectId const512Used when entry ID should be included in email subjects 
FormBuilderProcessor::formFlagInclude const2Used when for is intended as an include for other forms 
FormBuilderProcessor::formFlagNoModal const1Used when modal window for admin/editing should be disabled 

Spam flags

NameReturnSummary 
FormBuilderProcessor::spamFlagEntry const8Specifies that we should still save spam entries but flag them as spam 
FormBuilderProcessor::spamFlagNone const0Specifies that default reporting should be used for spam 
FormBuilderProcessor::spamFlagSilent const2Specifies that spam entries should be silently discarded 
FormBuilderProcessor::spamFlagVerbose const4Specifies that we should notify the persion submitting the form that spam was detected 

Additional methods and properties

In addition to the methods and properties above, FormBuilderProcessor also inherits the methods and properties of these classes:

API reference based on ProcessWire core version 3.0.252