Hooks are basically scripts that run after a form is validated by FormIt. They can be chained; the first hook will execute, and if succeeds, will proceed onto the next hook. If a hook fails, it will not proceed to the next hook, but return back to the form with any error messages sent.
Hooks may also be Snippet names, which will then execute the Snippet as a hook.
There are two types of hooks:
- A 'preHook', specified via the 'preHooks' property on the FormIt snippet, that executes when the form loads. Useful for pre-loading values.
- The normal hook, specified via the 'hooks' property on the FormIt snippet, that executes after the form is validated. Useful for custom post-processing.
Just specify the preHook in the 'preHooks' property in your FormIt snippet call. There are no built-in preHooks, but if you had a preHook called 'loadCustomValues':
Would then run the 'loadCustomValues' snippet before loading the form. You could then set fields on the form like so:
<?php $hook->setValue('name','John Doe'); $hook->setValue('email','email@example.com'); return true;
Or alternatively using ->setValues:
<?php $hook->setValues(array( 'name' => 'John Doe', 'email' => 'firstname.lastname@example.org', )); return true;
Note that using the setValues() method here will make the corresponding placeholders available to your email chunk; the effect of manually setting values is similar to adding hidden fields to your form.
You can do whatever you want in the preHook as well. Remember to return true if your preHook or Hook is successful. If you want to add an error message to a field:
$hook->addError('user','User not found.'); return $hook->hasErrors();
Simply specify the hook in the 'hooks' property in your FormIt snippet call. For example, this loads the spam and email hooks:
This is a list of the built-in hooks packaged with FormIt:
The redirect hook (if used) should always be the last hook specified. Remember that the hooks execute in the order they are specified in the property.
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 Hook
The Formit fields are available via the hook api. Example:
$email = $hook->getValue('email'); $allFormFields = $hook->getValues();
If you want to set fields, however, you'll need to access them this way:
$hook->setValue('email','email@example.com'); $hook->setValues(array( 'name' => 'John Doe', 'books' => 'Hunger Games,To Kill a Mockingbird,Mindset', ));
If you want to set an array field (i.e. a checkbox group with the same name, a select multiple field) in a preHook, you have to json_encode the array value.
Accessing FormIt scriptProperties (config)
Properties passed to the FormIt Snippet call are available in the config property of the $formit object exposed in a Hook.
Custom hook return values
Snippets should return true on success. On failure, the snippet can set error messages in the hook object's errors variable and return false. In either case, hooks listed after the custom hook in the &hooks parameter will not execute.
The fiHooks object is available in the snippet as $hook, which can be used to return generic error messages from the snippet:
$errorMsg = 'User not found'; $hook->addError('user',$errorMsg); return false;
Again, remember - if your hook succeeds, make sure you have "return true;" at the end of your Hook. If you use "return false;" or do not return a value, FormIt will assume the Hook failed. Also, be sure that any custom hooks you specify come before the redirect hook in the hooks property.
FormIt 2.0.0+ supports file-based hooks and preHooks. This means that you can point FormIt straight to a PHP file to use as a custom hook. For example:
[[!FormIt? &hooks=`[[++assets_path]]hooks/my.hook.php` ]]
This will evaluate the MODX tags in the hook line, and then look for the hook at assets/hooks/my.hook.php. If the file is found, it will evaluate the hook from there.