Documentation

FormHelper

The FormHelper module extends the PW form object and simplifies the form handling.

create basic PW form object with submit button
add form field value handling and sanitizing
take care about form submit / error state and processing
CKEditor pwImagePlugin field, jsConfig, load form admin styles

FormHelperExtra

FormHelperExtra is a submodule to handle additional features.

create a form object with fields based on Template, Page, Form objects or field data array
form file upload handling (temp page uploads)

FormHelper usage

Create forms using PW API

FormHelper documentation explains how to use the additional features. To learn how to use the PW form object and Inputfields take a look at Create simple forms using API written by Soma.

Load the module

Load the Processwire module as usual.

#!php
<?php
$fh = $modules->get('FormHelper');

Generate form

Generate form objects with submit button.

#!php
<?php
$form = $fh->create();

Additional field properties

FormHelper uses additional field properties.

#!php
<?php
// Set a default sanitizer to a field
$field->fhSanitizer = 'pageName';

// Set an ignore flag to a field
// to simplify automated field value handling (example: ignore submit button value)
$field->fhIgnore = true;

Modify the submit button

Get the submit button field to modify it.

#!php
<?php
$submitBtn = $form->fhSubmitBtn;

Use PW hooks to add field / form processing

Just use Processwire hooks to add additional field / form pre/post-process and pre-render processing.

#!php
<?php
// additional field processing during form process
$field->addHookAfter('processInput', function($event) {
    $field = $event->object;
    $this->pass = $field->value;
});

#!php
<?php
// change form field values after the field is processed
$field->addHookBefore('render', function($event) {
    $field = $event->object;
    $field->value = '';
});

InputfieldCKEditor helper

Create the needed additional field to use the pwImagePlugin.

#!php
<?php
$ckeditor = $modules->get('InputfieldCKEditor');
// configure ckeditor Inputfield...
$form->add($ckeditor);
$form->add($form->fhCkeditorImagePlugin($refImagePageId));
// ...

Example: process form

#!php
<?php
if ($form->fhProcessForm()) {
    // null     = not submitted
    // false    = submitted with errors
    // true     = submitted without errors

    // do something...

    // Get process state again 
    $state = $form->fhState;

    // Get sanitized value or raw if not set $field->fhSanitizer
    $form->fhValue($fieldname):

    // Get sanitized value with changed sanitizer
    $form->fhValue($fieldname, 'text'):

    // Get raw field value
    $form->fhValue($fieldname, false):

    // Add WireUpload files to a page field
    foreach ($fileField->fhFiles as $file) {
        $fieldName = $fileField->name;
        $page->$fileField->add($file);  // don't forget to save it later...
        unlink($file); // clean up temp file
    }
}

// Render the form before styles / scripts output
$output = $form->render();

// -- output this inside the <head></head> -- //
// Add jsConfig if needed...
echo $form->fhJsConfig();

// Output PW styles / Scripts
foreach ($config->styles as $file) { echo "<link type='text/css' href='$file' rel='stylesheet' />\n"; } 
foreach ($config->scripts as $file) { echo "<script type='text/javascript' src='$file'></script>\n"; }
// -- output this inside the <head></head> -- //

FormHelperExtra usage

Generate form by source

Generate form based on * Template object * Page object * InputfieldForm / InputfieldWrapper object * array of field data

Just add additional parameters to the create() method call.

$source: Build the form based on given source
$skip: Array with fields to skip during form creation
$refPage: use field settings like (file destination path, textformatter, ...) from refPage
$styled: load admin theme (backend) styles

Template based form

#!php
<?php
// Template based form, skip fields 'title' and 'privateField', unstyled
$form = $fh->create($templates->get('basic-page'), array('title', 'privateField'));

Page based form

#!php
<?php
// form based on Page with admin theme styles
$form = $fh->create($pages->get('title=PageTitle'), null, null, true);

InputfieldForm based form

#!php
<?php
$myFormObject; // PW form object with fields
$skipFields;   // Array with field names to skip

$form = $fh->create($myFormObject, $skipFields);

Array based form

It's also possible to create a form based on an array of field information (PW 2.5.5, blog post).

#!php
<?php
   $fieldArray = array(
      array(
        'name' => 'fullname',
        'label' => 'Full Name',
        'type' => 'text',
        'required' => true,
        'value' => '',
      ),
      array(
        'name' => 'color',
        'type' => 'select',
        'label' => 'Favorite Color',
        'options' => array(
          'red' => 'Red',
          'green' => 'Green',
          'blue' => 'Blue'
        ),
        'value' => 'blue',
      ),
      array(
        'name' => 'age',
        'type' => 'integer',
        'label' => 'Your Age',
        'value' => 40
      )
    ));

$form = $fh->create($fieldArray);

Wiki

FormHelper / Documentation