FormIt

FormIt is for MODx Revolution 2.0.0-beta-4 and later.

FormIt

FormIt is a dynamic form processing Snippet for MODx Revolution.

How to Use

Simply place the FormIt snippet call into the Resource that contains the form you want to use. Specify the "hooks" (or post-validation processing scripts) in the snippet call. Then add validation via filters to your form fields in your form.

Validation

Validation can simply be done by adding filters to your input fields. For example, to make a field required, you could do:

<input type="text" name="username:required" value="[[+fi.username]]" />

Validators can also be "chained", or done in sucession. The following first checks to see if required, then strips all tags from the post:

<textarea name="text:required:stripTags" id="text" cols="55" rows="7">[[+fi.text]]</textarea>

Built-In Validators

Validator as a Snippet

Validators can also be custom Snippets. You can do this by simply specifying the snippet name as a validator:

<input type="text" name="cost:isBigEnough" value="[[+fi.cost]]" />

Then in your Snippet, "isBigEnough":

<?php
$value = (float)$scriptProperties['value'];

return $value > 1000;
?>

The Validator will send the following properties to the snippet, in the $scriptProperties array:

Hooks

Hooks are basically scripts that run after the form is validated. Hooks can be chained; the first hook will execute, and if succeeds, will proceed onto the next hook.

Hooks may also be Snippet names, which will then execute the Snippet as a hook.

Built-in Hooks

There are only 3 built-in hooks to FormIt, and they are 'email, 'redirect' and 'spam'.

The email hook

The email hook will email out your form contents to any email(s). It requires the following properties to be passed into the snippet call:

The redirect hook

The redirect hook will redirect the user to a specified Resource when their form finishes submitting. It requires one parameter, redirectTo, which must the ID of the Resource you want to redirect to.

The spam hook

The spam hook will check all the fields specified in the property spamEmailFields against a spam filter via StopForumSpam (It will also check the IP of the submitter). If the user is flagged as a spammer, it will show an error message for that field checked.

The spam hook requires either cURL or Sockets support in your PHP installation (The same requirements for Package Management.

Custom hooks

Any snippet can be used as a custom hook with Formit. The snippet should return true on success and either false or an array of error messages on failure (see below). If the snippet returns false, hooks listed after the snippet in the &hooks parameter will not execute. If the snippet is not found, the hooks following it in the list will execute.

Registering custom hooks

To register a custom hook, just add the name of the snippet to the &hooks parameter. The hooks will execute in the order that they appear in the &hooks parameter. Your snippet can be at any position in the list.

Accessing the Formit fields in the snippet

The Formit fields are available in the snippet in the 'fields' member of the $scriptProperties array. Example:

$email = $scriptProperties['fields']['email'];

Custom hook return values

Snippets should return true on success. On failure, the snippet can set error messages in the hook object and return false, or it can simply return an array of error messages. In either case, hooks listed after the custom hook in the &hooks parameter will not execute.

The $hook object is available in the snippet in the 'hook' member of the $scriptProperties array, which can be used to return generic error messages from the snippet:

$errorMsg = 'User not found';
$scriptProperties['hook']->errors[] = $errorMsg;
return false;

Instead of returning false, the snippet can return field-specific error messages in an array:

return array(
   'email' => 'Invalid email address!',
   'subject' => 'Forbidden word in subject',
);

See Also

eForm

Home

Gallery